Volumes are the primary organizational unit in Tusky. Each volume acts as a secure container for files, with its own encryption settings, access policies, and member list. The tusky.volume module provides full CRUD operations and member management.
Create an Volume
Create a new volume with a name and optional configuration:
const volume = await tusky.volume.create("Project Assets", {
encrypted: true,
description: "Design files and brand assets",
defaultEpochs: 5,
autoExtend: true,
});
console.log("Created volume:", volume.id);
Options
| Parameter | Type | Default | Description |
|---|
encrypted | boolean | true | Enable client-side encryption for all files in this volume. |
description | string | — | Human-readable description of the volume. |
defaultEpochs | number | 3 | Default number of Walrus storage epochs for uploads. |
autoExtend | boolean | false | Automatically renew storage before epoch expiry. |
tags | string[] | — | Tags for filtering and organization. |
The encrypted setting is permanent and cannot be changed after the volume is created.
Get an Volume
Retrieve a volume by its ID:
const volume = await tusky.volume.get("vol_abc123");
console.log(volume.name); // "Project Assets"
console.log(volume.encrypted); // true
console.log(volume.fileCount); // 42
console.log(volume.totalSize); // 1073741824 (bytes)
List Volumes
Retrieve all volumes in your account:
const volumes = await tusky.volume.list();
for (const volume of volumes) {
console.log(`${volume.name} — ${volume.fileCount} files`);
}
The list is ordered by creation date (newest first) by default. You can use the returned metadata to build volume selectors, dashboards, or migration tools.
Update an Volume
Modify a volume’s mutable settings:
const updated = await tusky.volume.update("vol_abc123", {
name: "Brand Assets 2025",
description: "Updated brand guidelines and logos",
defaultEpochs: 10,
autoExtend: true,
});
console.log("Updated:", updated.name);
You can update the name, description, default epochs, auto-extend setting, and tags. The encryption type and volume ID are immutable.
Delete an Volume
Permanently remove a volume and its Tusky metadata:
await tusky.volume.delete("vol_abc123");
console.log("Volume deleted");
Deleting a volume removes all Tusky metadata and access control. Files already published to Walrus remain on the network until their storage epochs expire, but they will no longer be served through your Tusky aggregator.
Complete Example
import { Tusky } from "@tusky-io/ts-sdk";
const tusky = new Tusky({ apiKey: process.env.TUSKY_API_KEY });
// Create
const volume = await tusky.volume.create("Demo Volume", {
encrypted: false,
description: "Public demo content",
});
// Read
const fetched = await tusky.volume.get(volume.id);
console.log("Volume:", fetched.name, "| Encrypted:", fetched.encrypted);
// Update
await tusky.volume.update(volume.id, {
description: "Updated description",
});
// List all
const allDrives = await tusky.volume.list();
console.log("Total volumes:", allDrives.length);
// Delete
await tusky.volume.delete(volume.id);
console.log("Cleaned up");
What’s Next
