Volumes

import "github.com/declaw-ai/declaw-go"

A volume is a tenant-owned blob (gzip-compressed tar archive) that lives in Declaw’s object store. You upload a volume once with CreateVolume() and attach it to any number of sandboxes at create time via WithVolumes(). 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.

`declaw.CreateVolume()`

Upload a tar.gz and register it.

data, err := os.ReadFile("dataset.tar.gz")
if err != nil {
    log.Fatal(err)
}
vol, err := declaw.CreateVolume(ctx, "training-set-v1", data)
if err != nil {
    log.Fatal(err)
}
fmt.Println(vol.VolumeID, vol.SizeBytes)

string

required

Human-readable name. The server returns a stable VolumeID.

[]byte

required

The gzip-compressed tar archive. Must start with gzip magic bytes (0x1F 0x8B). Pass nil or empty for an empty volume.

Returns (*VolumeInfo, error)

`declaw.ListVolumes()`

List all volumes owned by the caller.

volumes, err := declaw.ListVolumes(ctx)
for _, v := range volumes {
    fmt.Println(v.VolumeID, v.Name, v.SizeBytes)
}

Returns ([]VolumeInfo, error)

`declaw.GetVolume()`

Fetch metadata for a single volume.

vol, err := declaw.GetVolume(ctx, "vol-abc123")

Returns (*VolumeInfo, error)

`declaw.DownloadVolume()`

Download the contents of a volume as raw bytes.

data, err := declaw.DownloadVolume(ctx, "vol-abc123")
if err != nil {
    log.Fatal(err)
}
_ = os.WriteFile("backup.tar.gz", data, 0644)

Returns ([]byte, error)

`declaw.DeleteVolume()`

Delete a volume by its ID.

err := declaw.DeleteVolume(ctx, "vol-abc123")

Returns error

Attaching to a sandbox

Pass WithVolumes() to Create():

vol, _ := declaw.CreateVolume(ctx, "dataset", tarGzBytes)

sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("python"),
    declaw.WithTimeout(600),
    declaw.WithVolumes([]declaw.VolumeAttachment{
        {VolumeID: vol.VolumeID, MountPath: "/data"},
    }),
)

// Files are already visible when the first command runs
result, _ := sbx.Commands.Run(ctx, "ls -la /data")
fmt.Println(result.Stdout)

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

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. File-granular volumes have a flat 64 GiB capacity cap.

Create a file-granular volume

vol, _ := declaw.CreateEmptyVolume(ctx, "scratch")        // empty
vol, _ = declaw.IngestVolume(ctx, "seed", tarGzBytes)     // or pre-populated from a tar.gz
fmt.Println(vol.Backend)   // "juicefs" / "local" (not "tarball")

Edit files without a sandbox — `VolumeFilesFor()`

files := declaw.VolumeFilesFor(vol.VolumeID)
files.Write(ctx, "/config/app.json", []byte(`{"k":"v"}`))   // parent dirs auto-created
files.Mkdir(ctx, "/data")
data, _ := files.Read(ctx, "/config/app.json")
entries, _ := files.List(ctx, "/")
for _, e := range entries {
    fmt.Println(e.Path, e.IsDir, e.Size)
}
files.Rename(ctx, "/config/app.json", "/config/app.prod.json")
files.Remove(ctx, "/data", true /* recursive */)

files.Info(ctx, path) returns a Version token; pass it via a WriteFileOption for an optimistic compare-and-set write (a 409 means the file changed underneath you).

Live-mount into a sandbox

files := declaw.VolumeFilesFor(vol.VolumeID)
files.Write(ctx, "/greeting.txt", []byte("hello from the files API"))

sbx, _ := declaw.Create(ctx,
    declaw.WithTemplate("base"),
    declaw.WithVolumes([]declaw.VolumeAttachment{
        {VolumeID: vol.VolumeID, MountPath: "/data", Mode: declaw.VolumeModeMount},
    }),
)
// The sandbox reads the files-API write over a live NFS mount...
result, _ := sbx.Commands.Run(ctx, "cat /data/greeting.txt")
fmt.Println(result.Stdout)
// ...and its writes are visible back through the files API immediately:
sbx.Commands.Run(ctx, "echo 'from the sandbox' > /data/out.txt")
out, _ := files.Read(ctx, "/out.txt")
fmt.Println(string(out))

Use declaw.VolumeModeMountRO 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 use declaw.VolumeModeCopy.

Mount a sub-path

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

sbx, _ := declaw.Create(ctx,
    declaw.WithTemplate("base"),
    declaw.WithVolumes([]declaw.VolumeAttachment{
        {VolumeID: vol.VolumeID, MountPath: "/data", Mode: declaw.VolumeModeMount, Subpath: "datasets/train"},
    }),
)

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
snap, _ := declaw.SnapshotVolume(ctx, sbx.ID, "/workspace/out", "run-42")

// An already-attached volume's mount path -> new volume
checkpoint, _ := declaw.CommitVolume(ctx, sbx.ID, src.VolumeID, "checkpoint")

SnapshotVolume captures any in-sandbox path; CommitVolume captures the mount path of an already-attached volume. Both return a new *VolumeInfo; pass "" for name to let the server default it. 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:

locks := declaw.VolumeLocksFor(vol.VolumeID)

lease, _ := locks.Acquire(ctx, "/data/model.bin", 60) // 409 (ConflictError) if already held
locks.Renew(ctx, "/data/model.bin", lease.Token, 60)
status, _ := locks.Status(ctx, "/data/model.bin")      // {Held: true, ExpiresInMs: ...}
locks.Release(ctx, "/data/model.bin", lease.Token)     // (released bool, error)

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

Data models

`VolumeInfo`

type VolumeInfo struct {
    VolumeID    string
    OwnerID     string
    Name        string
    BlobKey     string
    SizeBytes   int64
    ContentType string
    CreatedAt   string
    Metadata    map[string]string
    Backend     string // "tarball" (copy) | "local" | "juicefs" (file-granular)
    QuotaBytes  int64  // file-granular volumes; 0 = unlimited
}

`VolumeAttachment`

type VolumeAttachment struct {
    VolumeID  string
    MountPath string
    Mode      string // "copy" (default) | "mount" | "mount-ro"; see VolumeMode* constants
    Subpath   string // live-mount only; relative path within the volume
}

Python SDK

TypeScript SDK

Go SDK

`declaw.CreateVolume()`

`declaw.ListVolumes()`

`declaw.GetVolume()`

`declaw.DownloadVolume()`

`declaw.DeleteVolume()`

Attaching to a sandbox

File-granular volumes (live mounts)

Create a file-granular volume

Edit files without a sandbox — `VolumeFilesFor()`

Live-mount into a sandbox

Mount a sub-path

Snapshot a sandbox’s files into a volume

Advisory locks

Data models

`VolumeInfo`

`VolumeAttachment`

​declaw.CreateVolume()

​declaw.ListVolumes()

​declaw.GetVolume()

​declaw.DownloadVolume()

​declaw.DeleteVolume()

​Attaching to a sandbox

​File-granular volumes (live mounts)

​Create a file-granular volume

​Edit files without a sandbox — VolumeFilesFor()

​Live-mount into a sandbox

​Mount a sub-path

​Snapshot a sandbox’s files into a volume

​Advisory locks

​Data models

​VolumeInfo

​VolumeAttachment

`declaw.CreateVolume()`

`declaw.ListVolumes()`

`declaw.GetVolume()`

`declaw.DownloadVolume()`

`declaw.DeleteVolume()`

Attaching to a sandbox

File-granular volumes (live mounts)

Create a file-granular volume

Edit files without a sandbox — `VolumeFilesFor()`

Live-mount into a sandbox

Mount a sub-path

Snapshot a sandbox’s files into a volume

Advisory locks

Data models

`VolumeInfo`

`VolumeAttachment`