Skip to content

Volumes

Persistent volumes are ext4 filesystems that survive sandbox destruction. Create one, attach it to a sandbox, destroy the sandbox — the data is still there.

The CLI surface is in Volumes reference. This page covers the rules — when you can attach, what mount paths are allowed, and which operations require the volume to be unattached.

Volumes are mounted by lohar during sandbox boot. Specify them with --volume (repeatable):

Terminal window
bhatti volume create --name workspace --size 5120
bhatti create --name dev --volume workspace:/workspace

The format is <name>:<mount>[:ro]:

Terminal window
bhatti create --name reader --volume workspace:/data:ro

:ro mounts read-only. Multiple sandboxes can mount the same volume read-only at the same time — useful for shared base data. Read-write attachment is exclusive: only one sandbox can have it as read-write at any moment.

You can attach more than one volume per sandbox by repeating --volume.

Mount paths must be absolute. The guest agent rejects anything else.

You also can’t shadow system paths. Specifically, the following are blocked:

/proc /sys /dev /etc /usr /bin /sbin /lib /lib64 /run /var/run

Use a fresh subtree like /workspace, /data, /srv/<app> — anywhere outside the system hierarchy.

Four operations require the volume to have no sandbox attachments:

The server returns 409 Conflict if any sandbox still owns the attachment. Stopping a sandbox does not detach its volumes: it powers off the guest but retains its attachment for the next boot. To release one through the CLI, destroy that sandbox (the volume persists, its root disk does not). If you need to keep the sandbox, use a named memory snapshot to branch its whole device set rather than running a detached-only volume operation.

bhatti volume backup is the exception — it works while the volume is attached. The server holds the guest’s lifecycle, freezes the mounted filesystem on new running agents (or syncs on old agents), copies the volume locally, then thaws before compression/upload. The backup record’s consistency_mode is frozen, sync_only, or detached (no running attachment, including a stopped sandbox); historical backups can say unverified. Sync-only is not as strong as a freeze against concurrent writes. The CLI backup-list output omits this field; request the API record when you need it.

Volume backups go to S3-compatible storage (AWS, Backblaze B2, R2, MinIO, etc.). They require a backup block in the server config; without it, backup-related commands return 501.

Terminal window
bhatti volume backup workspace
bhatti volume backup-list workspace
bhatti volume restore workspace --backup-id bk_a1b2c3d4

Schedule regular backups with retention via the backup.schedule config — see Configuration.

A named memory snapshot also captures copies of attached volumes; each resume or live fork gets independent volume copies rather than sharing the original volume. A filesystem snapshot captures only the root disk, not attached volumes or the source’s network policy; preserve volume data separately.