Data & durability
A sandbox has a root disk, optional attached volumes, and running memory. I choose the recovery boundary before putting important work in one: stop keeps disks, not processes; a named memory snapshot is what keeps a running process state.
| Event | Files on root disk | Attached volumes | Processes and /tmp |
|---|---|---|---|
bhatti stop, then start | Kept | Kept and re-attached | Lost; guest boots again |
| Thermal warm pause | Kept | Kept | Paused in mapped memory; resumed on request |
| Thermal cold power-off | Kept | Kept | Lost; next request cold-boots |
Named snapshot create (default memory) | Copied | Copied; new copies attached on resume | Captured and continued on resume |
snapshot create --type filesystem | Copied | Not captured; preserve separately | Not captured; resume cold-boots |
| Daemon restart/update | Kept | Kept | Running v2.4+ VMs can be adopted if their helpers survive; otherwise disk recovery, not a process guarantee |
| Host reboot or unexpected power loss | Kept if flushed to storage | Kept if flushed/backed up | Lost without an explicit memory snapshot |
Stop and thermal cold are power-offs, not hidden full-memory checkpoints. The guest’s ephemeral /tmp and one-shot jobs go away; create with --init for work that must start again on cold boot. --keep-hot is useful for active connections, but it is not a backup or a host power-loss guarantee. External TCP peers will not necessarily keep a connection even when you restore a named memory snapshot.
Flush writes deliberately
Section titled “Flush writes deliberately”Ordinary bhatti exec no longer forces a guest-wide sync after every command. If your agent writes a file and needs it on disk before acknowledging success, opt in:
bhatti exec dev --sync -- ./write-important-dataThe API equivalent is POST /sandboxes/:id/exec with "sync": true. The guest sync runs before command completion is reported. --sync and --detach cannot be combined. Recent servers also sync before pausing a guest; a warm stop wakes and syncs before powering off. The guest limits dirty writeback to about five seconds. If synchronization fails at a stop boundary, the server emits sandbox.unclean_stop; inspect it with bhatti admin events --type sandbox.unclean_stop and check the affected filesystem before trusting the stopped state. None of these replaces an off-host backup in the face of disk loss.
Sandboxes created before v2.4 retain an older lohar inside their image. Newer guest capabilities, including grant handling, fork or root-disk growth, can return 409 asking you to recreate the sandbox; after updating the server, recreate old sandboxes to get the full guest-side durability behavior.
Root disk, volumes, and backups
Section titled “Root disk, volumes, and backups”The root disk is a private copy-on-write overlay; destroying the sandbox deletes it. Persistent volumes survive sandbox destruction and can be attached at create time with --volume workspace:/workspace. Stopping does not detach them: volume resize, clone, and restore require zero attachments, so a stopped sandbox still blocks those operations. A volume is not automatically an off-site backup. Choose volume backup for S3-compatible storage; restoring a backup requires a volume unattached to every sandbox.
You can back up a volume while the guest is running. The server holds its lifecycle, quiesces each running attachment, copies the volume locally, then releases the guest before compression/upload. New agents freeze/thaw the guest filesystem (consistency_mode: frozen); older agents sync only (sync_only); a volume with no running attachments (including one attached to a stopped sandbox) records detached. Historical backups without a recorded consistency mode can show unverified. Sync-only does not protect concurrent writers as strongly as a frozen filesystem. The full API backup record has consistency_mode; the CLI backup-list table and its JSON representation currently show only ID, size, and creation time. Schedule backups and check a restore path instead of assuming a local copy will survive host failure.
A named memory snapshot captures RAM, CPU state, the root disk, attached-volume copies and network policy; each resumed sandbox gets cloned, re-attached volume copies. A filesystem snapshot captures only the root disk and cold-boots a fresh sandbox without the source’s volumes or network policy; preserve volume data separately. Snapshots are for branching or restoring a particular state; export/import carries that checkpoint to a compatible host, not a substitute for independently backed-up application data.