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 idea¶

create volume ──▶ attach to machine A ──▶ write data ──▶ destroy A
            └──▶ attach to machine B ──▶ data is still there

A volume is an independent disk; machines come and go, the volume persists until you delete it.

Create and attach (REST API)¶

Volume lifecycle is exposed on the REST API (the SDK's Sandbox helper focuses on run-and-destroy). Use the API or Client:

# 1. create a 10 GB volume
curl -X POST https://api.sistemo.io/v1/volumes \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-data","size_gb":10}'

# 2. attach it to a stopped machine (same host)
curl -X POST "https://api.sistemo.io/v1/volumes/$VOL/attach" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"machine_id":"'"$MACHINE"'"}'

See the full Volumes API for detach/delete and the rules (attach requires a stopped machine on the same host).

Prove it survives¶

# inside machine A (volume mounted, e.g. at /mnt/agent-data):
echo "run-$(date +%s)" > /mnt/agent-data/state.txt
# destroy A, create B, attach the same volume, then:
cat /mnt/agent-data/state.txt        # your string is still there

Keep a sandbox's own disk¶

If you just want to keep the machine's root disk after destroying it (rather than a separate volume), close with preserve_storage:

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

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

When to use which¶