Volumes

A volume is a named, owner-owned store of files that lives outside any single sandbox. Unlike a sandbox’s own filesystem — which is ephemeral, private, and gone when the sandbox is killed — a volume persists, and you can attach it to any number of sandboxes at a mount path. Volumes carry data (datasets, model weights, an agent’s working tree); templates define the base image a sandbox boots from.

Two kinds of volume

	Copy-mode	File-granular
What it is	A gzip tar archive hydrated into the sandbox’s filesystem at boot	A persistent, shared filesystem you can edit directly — with or without a running sandbox
Reads/writes	Read-at-boot; guest writes stay private to that sandbox and never flow back	Live read and write; changes are shared and durable
Attach modes	`copy`	`mount` (read-write) or `mount-ro` (read-only)
Edit without a sandbox	No	Yes — read/write/list/delete files over the API
Best for	Seeding many parallel sandboxes from the same source (fanout, CI)	A shared workspace multiple sandboxes (or agents) read and write concurrently

Both are owner-scoped — you can only attach your own volumes.

Create and attach (copy-mode)

Upload a gzip tar archive once, then attach it to sandboxes at create time. On boot, the archive is materialized under the attachment’s mount_path before the first command runs.

Python
TypeScript

from declaw import Sandbox, Volumes, VolumeAttachment

# Upload once (bytes, a file-like object, or a path to a file/dir)
vol = Volumes.create("training-data", data="./data")
print(vol.volume_id, vol.size_bytes)

# Attach to any number of sandboxes
sbx = Sandbox.create(
    template="python",
    volumes=[VolumeAttachment(volume_id=vol.volume_id, mount_path="/data")],
)
print(sbx.commands.run("ls /data").stdout)

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

const vol = await Volumes.create('training-data', tarGzBytes);

const sbx = await Sandbox.create({
  template: 'python',
  volumes: [{ volumeId: vol.volumeId, mountPath: '/data' }],
});
console.log((await sbx.commands.run('ls /data')).stdout);

The same volume can be attached to many sandboxes in parallel — each gets its own private copy, so there’s no contention.

File-granular volumes (live mounts)

A file-granular volume is a shared filesystem you can edit from the SDK with no sandbox running, and live-mount into a sandbox so reads and writes go straight to the shared volume. Create one empty (or seed it from an archive), edit its files directly, then mount it read-write.

Python
TypeScript

from declaw import Sandbox, Volumes, VolumeAttachment

# Create an empty file-granular volume and edit it without a sandbox
vol = Volumes.empty("workspace")
files = Volumes.files(vol.volume_id)
files.write("/notes.txt", b"seeded from the SDK\n")
print(files.list("/"))

# Live-mount it read-write; guest writes are shared and durable
sbx = Sandbox.create(
    template="base",
    volumes=[VolumeAttachment(
        volume_id=vol.volume_id, mount_path="/work", mode="mount",
    )],
)
sbx.commands.run("echo 'from the sandbox' >> /work/notes.txt")
print(files.read("/notes.txt"))   # includes both lines

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

const vol = await Volumes.create('workspace');   // empty file-granular
const files = Volumes.files(vol.volumeId);
await files.write('/notes.txt', new TextEncoder().encode('seeded from the SDK\n'));

const sbx = await Sandbox.create({
  template: 'base',
  volumes: [{ volumeId: vol.volumeId, mountPath: '/work', mode: 'mount' }],
});
await sbx.commands.run("echo 'from the sandbox' >> /work/notes.txt");
console.log(new TextDecoder().decode(await files.read('/notes.txt')));

Use mode="mount-ro" for a read-only mount (guest writes are rejected). 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):

Python
TypeScript

VolumeAttachment(
    volume_id=vol.volume_id, mount_path="/data", mode="mount",
    subpath="datasets/train",   # mounts <volume>/datasets/train at /data
)

{
  volumeId: vol.volumeId, mountPath: '/data', mode: 'mount',
  subpath: 'datasets/train',   // mounts <volume>/datasets/train at /data
}

Snapshot and commit

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

Python
TypeScript

# Any absolute in-sandbox path -> new volume
vol = Volumes.snapshot(sbx.sandbox_id, path="/workspace/out", name="run-42")

# An already-attached volume's mount path -> new volume
checkpoint = Volumes.commit(sbx.sandbox_id, volume_id=src.volume_id, name="checkpoint")

const snap = await Volumes.snapshot(sbx.sandboxId, '/workspace/out', 'run-42');
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 volume and leave the source untouched. Synthetic paths (/proc, /sys, /dev) are rejected.

Coordinate writers with advisory locks

When several sandboxes share a live-mounted volume, coordinate writers with advisory leases over a (volume, path) pair. acquire returns a token you present to renew / release:

Python
TypeScript

locks = Volumes.locks(vol.volume_id)

lease = locks.acquire("/data/model.bin", ttl_seconds=60)   # 409 if already held
token = lease["token"]
locks.renew("/data/model.bin", token, ttl_seconds=60)
print(locks.status("/data/model.bin"))                     # {"held": True, "expires_in_ms": ...}
locks.release("/data/model.bin", token)

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

const lease = await locks.acquire('/data/model.bin', 60);  // 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);

Locks are advisory — they coordinate cooperating writers; they don’t block I/O from code that ignores them. For atomic read-modify-write, file-granular writes also support a compare-and-swap (if_version) check.

Limits

Format: uploads are gzip-compressed tar archives (application/gzip). Only regular files are materialized — symlinks, hardlinks, device nodes, and entries containing .. are dropped for safety.
Upload size: the upload body is capped at 4 GiB.
File-granular capacity: a flat 64 GiB per-volume cap (a hard abuse-prevention ceiling, not a per-tier quota — volumes are not tier-gated).
Ownership: strictly owner-scoped; you can attach only your own volumes. A volume that is still live-mounted by a sandbox cannot be deleted.

VolumeInfo model

Field	Type	Description
`volume_id`	`str`	Unique identifier
`name`	`str`	Human-readable name you set at creation
`size_bytes`	`int`	Current size of the volume’s contents
`created_at`	`str`	When the volume was created (ISO-8601 string)
`metadata`	`dict`	Arbitrary key-value pairs attached at creation
`quota_bytes`	`int`	Capacity cap for file-granular volumes (`0` = unlimited)

Use cases

Stage data before the sandbox exists

Upload a dataset once, then fan out many parallel sandboxes that each read the same files at boot — no per-sandbox upload step.

vol = Volumes.create("dataset", data="./big-dataset")
workers = [
    Sandbox.create(template="python",
                   volumes=[VolumeAttachment(volume_id=vol.volume_id, mount_path="/data")])
    for _ in range(10)
]

Shared workspace for multiple agents

Live-mount one file-granular volume into several sandboxes so a team of agents reads and writes a common workspace. Serialize concurrent writers with advisory locks.

vol = Volumes.empty("shared-workspace")
a = Sandbox.create(volumes=[VolumeAttachment(vol.volume_id, "/work", mode="mount")])
b = Sandbox.create(volumes=[VolumeAttachment(vol.volume_id, "/work", mode="mount")])
# Both see each other's writes under /work

Checkpoint a result into a versioned volume

Capture a sandbox’s output directory into a new volume after an expensive step, so you can restore or share it later.

sbx.commands.run("python3 train.py --out /workspace/model")
artifact = Volumes.snapshot(sbx.sandbox_id, path="/workspace/model", name="model-v3")

For the full method reference, see the SDK volume guides (Python, TypeScript, Go) and the Volumes API. For runnable examples, see the Volumes cookbook.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Two kinds of volume

Create and attach (copy-mode)

File-granular volumes (live mounts)

Mount a sub-path

Snapshot and commit

Coordinate writers with advisory locks

Limits

VolumeInfo model

Use cases

​Two kinds of volume

​Create and attach (copy-mode)

​File-granular volumes (live mounts)

​Mount a sub-path

​Snapshot and commit

​Coordinate writers with advisory locks

​Limits

​VolumeInfo model

​Use cases

Two kinds of volume

Create and attach (copy-mode)

File-granular volumes (live mounts)

Mount a sub-path

Snapshot and commit

Coordinate writers with advisory locks

Limits

VolumeInfo model

Use cases