Take and restore snapshots

Capture a sandbox disk state and fork fresh sandboxes from that point.

A snapshot captures the full disk state of a running sandbox and returns a new Image that you can pass to Sandbox.ephemeral() or Sandbox.create() to start a fresh sandbox from that point.

Snapshot and restore

Snapshots are currently supported on Cua Cloud sandboxes. Local sandboxes (Docker, Lume, QEMU) have limited snapshot support.

Call snapshot() on a running sandbox after you make the changes you want to keep.

import asyncio
from cua import Sandbox, Image
 
async def main():
    async with Sandbox.ephemeral(Image.linux('ubuntu', '24.04')) as sb:
        await sb.shell.run('apt-get update -qq && apt-get install -y -qq cowsay')
        cowsay_image = await sb.snapshot(name='with-cowsay')
 
    # boot from snapshot — cowsay already installed
    async with Sandbox.ephemeral(cowsay_image) as sb2:
        result = await sb2.shell.run('/usr/games/cowsay hello from snapshot!')
        print(result.stdout)
 
asyncio.run(main())

Signature:

await sb.snapshot(name='my-snapshot', stateful=False)

Parameters:

name: str | None: optional human-readable label
stateful: bool (default False): capture memory state in addition to disk (VMs only)

Returns: an Image

Pre-bake an environment once, fork many times

Snapshot after slow setup, then reuse that image for repeated runs.

async with Sandbox.ephemeral(Image.linux()) as sb:
    await sb.shell.run('apt-get update && apt-get install -y python3-pip ffmpeg')
    await sb.shell.run('pip install torch transformers')
    ml_image = await sb.snapshot(name='ml-ready')
 
for lr in [0.001, 0.01, 0.1]:
    async with Sandbox.ephemeral(ml_image) as sb:
        await sb.shell.run(f'python train.py --lr {lr}')

Isolate state between runs

Each fork gets its own copy of disk, changes in one fork never affect another.

async with Sandbox.ephemeral(Image.linux()) as sb:
    await sb.shell.run('echo original > /tmp/data.txt')
    base = await sb.snapshot(name='base')
 
async with Sandbox.ephemeral(base) as a:
    await a.shell.run('echo fork-a >> /tmp/data.txt')
 
async with Sandbox.ephemeral(base) as b:
    result = await b.shell.run('cat /tmp/data.txt')
    print(result.stdout)  # 'original\n' — no trace of fork-a

Performance

Operation	Typical time
Create + install packages	30-120 s
Fork from snapshot	1-5 s

On backends that use copy-on-write storage, forking is nearly instant regardless of disk image size. On dir storage backends, the fork performs a full copy.