Persist data with volumes¶

By default a sandbox's disk is reclaimed when you destroy it. To keep data across destroy/recreate — datasets, a model cache, an agent's working directory — use a volume.

The SDK Sandbox() helper is create-run-destroy. Volumes are on the REST API (full-scope key). Attach requires a stopped machine on the same host.

The idea¶

create volume ──▶ attach to stopped machine A ──▶ start A ──▶ mount /dev/vdb ──▶ write
destroy A ──▶ attach to stopped machine B ──▶ start B ──▶ mount /dev/vdb ──▶ data is still there

A volume is an independent disk. It shows up in the guest as the next drive (/dev/vdb for the first data disk). Nothing auto-mounts it — you mount it.

The image is already ext4 (formatted at create). First attach: mkdir + mount. Later attaches to a new machine: same, no mkfs (that would wipe it).

Create, attach, write, prove it¶

export SISTEMO_API_KEY=sk_live_xxxxxxxxxxxxxxxx
API=https://api.sistemo.io

# 1. A machine you will stop (or create one and stop it).
MACHINE=...   # uuid
VOL=$(curl -sS -X POST "$API/v1/volumes" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-data","size_gb":10}' | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 2. Machine must be stopped. Same host as the volume after create (placement).
curl -sS -X POST "$API/v1/volumes/$VOL/attach" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"machine_id\":\"$MACHINE\"}"

curl -sS -X POST "$API/v1/machines/$MACHINE/start" \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

# 3. Inside the guest (exec or terminal) — first data disk is vdb:
curl -sS -X POST "$API/v1/machines/$MACHINE/execs" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exec_id":"mount-1","script":"mkdir -p /mnt/data && mount /dev/vdb /mnt/data && echo hello > /mnt/data/state.txt && cat /mnt/data/state.txt","timeout_sec":120}'

Destroy that machine, attach $VOL to a new stopped machine, start it, mount /dev/vdb /mnt/data, cat /mnt/data/state.txt — the string is still there.

See Volumes API for detach/delete. Free tier allows 2 volumes, and 30 GB of storage in total — which includes each machine's own root disk, so a free account running one 10 GB Sandbox() has 20 GB left for volumes. A volume is at least 5 GB.

Keep a sandbox's own disk¶

If you just want the root disk after destroy (not a separate volume), close with preserve_storage. That disk is re-attachable; it is not mounted for you.

from sistemo import Sandbox

sb = Sandbox()
try:
    sb.run("echo important > /root/state.txt")
finally:
    sb.close(preserve_storage=True)      # disk kept as a volume

import { Sandbox } from "@sistemo/sdk";

const sb = await Sandbox.create();
try {
  await sb.run("echo important > /root/state.txt");
} finally {
  await sb.close(true);                 // preserveStorage
}

When to use which¶

Volumes bill while they exist, running or not, per second at the GB-month rate. Delete them when you are done.