Volumes

import { Sandbox, Volumes } from '@declaw/sdk';
import type { VolumeInfo, VolumeAttachment } from '@declaw/sdk';

A volume is a tenant-owned blob (gzip-compressed tar archive) that lives in Declaw’s object store. You upload a volume once with Volumes.create(...) and attach it to any number of sandboxes at create time via Sandbox.create({ volumes: [...] }). On boot, Declaw streams the blob from object storage and materializes its regular-file entries under the attachment’s mountPath before the first command runs.

How volumes work

Format: only gzip-compressed tar archives (application/gzip). Symlinks, hardlinks, device nodes, and entries containing .. are dropped on the server.
Size: the upload body is capped at 4 GiB; a file-granular volume has a flat 64 GiB capacity cap.
Semantics: read-at-boot. A volume is materialized into each sandbox’s overlay filesystem when it attaches. Writes inside the sandbox are private to that sandbox and never flow back to the volume.
Ownership: a volume is strictly owner-scoped. You can attach only your own volumes.

`Volumes.create()`

Upload a tar.gz and register it. The body is a Uint8Array or ArrayBuffer; pass a streaming body from disk by reading with fs.readFile, or build it in-memory (see the cookbook for a zero-dep tar writer).

import { readFile } from 'node:fs/promises';
import { Volumes } from '@declaw/sdk';

const bytes = await readFile('dataset.tar.gz');
const vol = await Volumes.create('training-set-v1', bytes);
console.log(vol.volumeId, vol.sizeBytes);

Signature

Volumes.create(
  name: string,
  data: Uint8Array | ArrayBuffer,
  opts?: VolumeCreateOpts,
): Promise<VolumeInfo>

string

required

Human-readable name. Not used for addressing — the server returns a stable volumeId.

Uint8Array | ArrayBuffer

required

The raw tar.gz bytes to upload.

string

default:"'application/gzip'"

Content-Type header sent with the upload. Leave as the default.

string

Override the API key from environment.

string

Override the API domain (e.g. api.declaw.ai).

number

Per-request timeout in milliseconds. Raise this for multi-GiB uploads.

`Volumes.list()`

List all volumes owned by the caller, newest first.

for (const v of await Volumes.list()) {
  console.log(v.volumeId, v.name, v.sizeBytes);
}

`Volumes.get()`

Fetch metadata for a single volume.

const vol = await Volumes.get('vol-abc123');

Throws NotFoundError if the volume does not exist or is owned by a different tenant.

`Volumes.delete()`

Delete the blob and the metadata row.

await Volumes.delete('vol-abc123');

Attaching to a sandbox

Pass volumes: [...] to Sandbox.create:

import { Sandbox, Volumes } from '@declaw/sdk';
import type { VolumeAttachment } from '@declaw/sdk';

const vol = await Volumes.create('dataset', await readFile('dataset.tar.gz'));

const sbx = await Sandbox.create({
  template: 'python',
  timeout: 600,
  volumes: [{ volumeId: vol.volumeId, mountPath: '/data' }],
});

const result = await sbx.commands.run('ls -la /data');
console.log(result.stdout);

VolumeAttachment[]

One or more attachments. Each is { volumeId: string, mountPath: string }. mountPath must be an absolute path and must not target a system directory (/, /etc, /usr, /proc, /sys, /dev, /bin, /sbin, /lib, /lib64, /var, /run, /boot).

The same volumeId can appear in many sandbox-create calls in parallel; each sandbox gets its own materialized copy on its overlay.

File-granular volumes (live mounts)

The volumes above are copy-mode: a tar.gz hydrated into the sandbox at boot, with writes private to each sandbox. A file-granular volume is different — you can edit its files directly from the SDK (no sandbox), and live-mount it into a sandbox so reads and writes go straight to the shared volume.

	Copy (`Volumes.create`)	File-granular (`Volumes.empty` / `ingest`)
Created from	a tar.gz blob	empty, or a tar.gz (`ingest`)
Edit without a sandbox	no	yes — the `files` API
Attach mode	`copy` (hydrate at boot)	`copy`, `mount` (rw), or `mount-ro`
Sandbox writes flow back	no (private copy)	yes (live mount)

Create a file-granular volume

const vol = await Volumes.empty('scratch');               // empty
const vol2 = await Volumes.ingest('seed', tarGzBytes);    // or from a tar.gz (Uint8Array)
console.log(vol.backend);   // "juicefs" / "local" (not "tarball")

Edit files without a sandbox — `Volumes.files()`

const files = Volumes.files(vol.volumeId);
await files.write('/config/app.json', new TextEncoder().encode('{"k":"v"}')); // parent dirs auto-created
await files.mkdir('/data');
console.log(new TextDecoder().decode(await files.read('/config/app.json')));
for (const e of await files.list('/')) console.log(e.path, e.isDir, e.size);
await files.rename('/config/app.json', '/config/app.prod.json');
await files.remove('/data', { recursive: true });

files.info(path) returns a version token; pass it to write(path, data, { ifVersion }) for an optimistic compare-and-set write — a ConflictError (409) means the file changed underneath you.

Live-mount into a sandbox

const files = Volumes.files(vol.volumeId);
await files.write('/greeting.txt', new TextEncoder().encode('hello from the files API'));

const sbx = await Sandbox.create({
  template: 'base',
  volumes: [{ volumeId: vol.volumeId, mountPath: '/data', mode: 'mount' }],
});
// The sandbox reads the files-API write over a live NFS mount...
console.log((await sbx.commands.run('cat /data/greeting.txt')).stdout);
// ...and its writes are visible back through the files API immediately:
await sbx.commands.run("echo 'from the sandbox' > /data/out.txt");
console.log(new TextDecoder().decode(await files.read('/out.txt')));

Use mode: 'mount-ro' for a read-only mount — guest writes are rejected with a read-only-filesystem error. Live mounts require a file-granular volume; copy-mode volumes can only be attached with mode: 'copy'.

Mount a sub-path

Mount just part of a volume with subpath (live-mount only — the server rejects subpath on a copy attachment):

const sbx = await Sandbox.create({
  template: 'base',
  volumes: [{
    volumeId: vol.volumeId,
    mountPath: '/data',
    mode: 'mount',
    subpath: 'datasets/train',   // mounts <volume>/datasets/train at /data
  }],
});

Snapshot a sandbox’s files into a volume

Capture filesystem state from a running sandbox into a new volume — the source is never modified:

// Any absolute in-sandbox path -> new volume
const snap = await Volumes.snapshot(sbx.sandboxId, '/workspace/out', 'run-42');

// An already-attached volume's mount path -> new volume
const checkpoint = await Volumes.commit(sbx.sandboxId, src.volumeId, 'checkpoint');

snapshot captures any in-sandbox path; commit captures the mount path of a volume already attached to that sandbox. Both return a new VolumeInfo; the name arg is optional. Synthetic paths (/proc, /sys, /dev) are rejected.

Advisory locks

Coordinate writers to a shared (live-mounted) volume with advisory leases over a (volume, path) pair. acquire returns a token you must present to renew / release:

const locks = Volumes.locks(vol.volumeId);

const lease = await locks.acquire('/data/model.bin', 60);   // ConflictError (409) if already held
await locks.renew('/data/model.bin', lease.token, 60);
console.log(await locks.status('/data/model.bin'));         // { held: true, expiresInMs: ... }
await locks.release('/data/model.bin', lease.token);        // true if released

Locks are advisory — they coordinate cooperating writers; they don’t block I/O from code that ignores them.

`VolumeInfo` shape

interface VolumeInfo {
  volumeId: string;      // "vol-..."
  ownerId: string;
  name: string;          // human-readable, supplied at create
  blobKey: string;       // object-store path, for reference
  sizeBytes: number;
  contentType: string;   // "application/gzip"
  metadata: Record<string, string>;
  createdAt: string;     // ISO-8601
}

Errors

Situation	Error class	HTTP
Volume not found or not owned by caller	`NotFoundError`	404
`mountPath` is a system directory or relative	`InvalidArgumentError`	400
Referenced `volumeId` doesn’t belong to caller at attach time	`AuthenticationError`	403
Upload body exceeds 4 GiB	`InvalidArgumentError`	413

Python SDK

TypeScript SDK

Go SDK

How volumes work

`Volumes.create()`

`Volumes.list()`

`Volumes.get()`

`Volumes.delete()`

Attaching to a sandbox

File-granular volumes (live mounts)

Create a file-granular volume

Edit files without a sandbox — `Volumes.files()`

Live-mount into a sandbox

Mount a sub-path

Snapshot a sandbox’s files into a volume

Advisory locks

`VolumeInfo` shape

Errors

See also

​How volumes work

​Volumes.create()

​Volumes.list()

​Volumes.get()

​Volumes.delete()

​Attaching to a sandbox

​File-granular volumes (live mounts)

​Create a file-granular volume

​Edit files without a sandbox — Volumes.files()

​Live-mount into a sandbox

​Mount a sub-path

​Snapshot a sandbox’s files into a volume

​Advisory locks

​VolumeInfo shape

​Errors

​See also

How volumes work

`Volumes.create()`

`Volumes.list()`

`Volumes.get()`

`Volumes.delete()`

Attaching to a sandbox

File-granular volumes (live mounts)

Create a file-granular volume

Edit files without a sandbox — `Volumes.files()`

Live-mount into a sandbox

Mount a sub-path

Snapshot a sandbox’s files into a volume

Advisory locks

`VolumeInfo` shape

Errors

See also