Persistent volumes

By default, a sandbox's rootfs is discarded when the sandbox is deleted. Volumes are attachable block devices that persist independently and can be mounted into any sandbox.

Creating a volume

$ pandastack volumes create --size 10G my-data
vol_8d2f1a  10 GiB  ready

Volumes are backed by sparse files in /var/lib/damroo/volumes/<vol-id>.img and exposed to the guest as a virtio-block device.

Attaching to a sandbox

from pandastack import Sandbox, Volume

vol = Volume.get("vol_8d2f1a")

sb = Sandbox(
    template="python-data",
    volumes=[{"id": vol.id, "mount": "/mnt/data"}],
)

sb.run("ls /mnt/data")

The volume mounts as /dev/vdb inside the guest and damroo-init ensures it's formatted (ext4) and mounted to the requested path before SSH becomes ready.

Lifecycle

• A volume can be attached to at most one running sandbox at a time.
• Detaching is automatic on sandbox delete.
• Volumes persist across agent restarts and workspace re-deploys.
• You can snapshot a volume independently of the sandbox using it.

Use cases

• Workspace persistence — user opens code-interpreter, attaches their /workspace volume.
• Large datasets — mount a 100 GiB volume once, share read-only across sandbox forks.
• CI cache — mount /root/.cache so subsequent runs reuse downloaded deps.

# Read-only attach (multiple sandboxes can mount the same RO volume)
sb = Sandbox(template="rust", volumes=[{"id": vol.id, "mount": "/cache", "readonly": True}])