#Volume Backends

Volume backend selection controls where Volume data lives and which storage operations are available.

The default backend is s0fs. It stores Sandbox0-managed filesystem state in S3-compatible object storage and keeps filesystem metadata under Sandbox0 control. Use s0fs for agent workspaces that need direct file APIs, snapshots, restore, forks, and small-file write-heavy behavior.

The s3 backend mounts an existing S3-compatible bucket prefix through the same ctld volume portal used by normal Sandbox mounts. Use s3 when the bucket prefix is the source of truth and a Sandbox should read or write objects through a mounted filesystem path.

Compatibility#

Snapshot, restore, and fork APIs are s0fs-only. Calling them on an s3 backend Volume returns a bad request because the backend does not support those operations.

S0FS Backend#

s0fs is the default backend when backend is omitted. It is the backend behind Sandbox0's normal persistent Volume behavior:

• durable filesystem metadata and file segments are stored in object storage
• direct Volume file APIs can operate without a running Sandbox
• snapshots record immutable point-in-time Volume state
• restore moves a Volume back to a snapshot state
• fork creates an independent child Volume with copy-on-write sharing
• persisted S0FS objects and node-local cache state can be protected with Sandbox0 application-layer encryption

Create an s0fs Volume by omitting backend:

bash
s0 volume create --access-mode RWO

S3 Backend#

The s3 backend projects object keys into a filesystem-like tree. It is useful when data already lives in object storage and the Sandbox should work against that bucket prefix directly.

For a workflow-oriented walkthrough, see Mount an S3 Bucket in an AI Agent Sandbox.

Create an S3 backend volume with the SDKs or CLI:

go
volume, err := client.CreateVolume(ctx, apispec.CreateSandboxVolumeRequest{
  Backend:    apispec.NewOptVolumeBackend(apispec.VolumeBackendS3),
  AccessMode: apispec.NewOptVolumeAccessMode(apispec.VolumeAccessModeRWO),
  S3: apispec.NewOptCreateSandboxVolumeS3Config(apispec.CreateSandboxVolumeS3Config{
      Provider: apispec.NewOptCreateSandboxVolumeS3ConfigProvider(
          apispec.CreateSandboxVolumeS3ConfigProviderAWS,
      ),
      Bucket: "sandbox-data",
      Prefix: apispec.NewOptString("team-a/workspace-a"),
      Region: apispec.NewOptString("us-east-1"),
      AccessKey: os.Getenv("AWS_ACCESS_KEY_ID"),
      SecretKey: os.Getenv("AWS_SECRET_ACCESS_KEY"),
  }),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("S3 volume ID: %s\n", volume.ID)

The bucket must already exist and be reachable with the per-Volume credentials you provide. The prefix can be empty or pre-existing.

provider can be aws, ali, or r2. Use ali for Aliyun OSS and r2 for Cloudflare R2. endpoint_url is required for ali and r2. For aws, provide region or an S3-compatible endpoint_url. access_key and secret_key are required; session_token is optional for temporary credentials.

The s3 backend is mount-s3-like rather than a full s0fs replacement:

• object keys are projected into directories using /
• directory entries are synthetic, or represented by zero-byte marker objects ending in /
• new files are written back to S3 on close, release, or fsync
• external S3 object changes are visible through the mounted path on later lookup, read, or list operations
• writable opens replace the target object and must write sequentially
• append writes and random in-place overwrites are not supported
• RWX, snapshots, restore, forks, direct file APIs without an active mounted owner, rename, hard links, symlinks, xattrs, locks, fallocate, and copy_file_range are not supported

When an s3 Volume is actively mounted, direct Volume file API requests can still be proxied to that active ctld owner. When it is not mounted, use S3 APIs directly or mount it into a Sandbox first.

Next Steps#