Save, restore, fork

Save a snapshot when you want to return to a sandbox’s current state. It includes files, memory, and running processes. Use a fork when you want another working copy immediately.

Save and restore

Create a sandbox, write a file, and save a durable checkpoint:

from lithosbox import LithosBox

box = LithosBox()
sandbox = box.sandboxes.create()
sandbox.files.write("/work/result.txt", "First result\n")
snapshot = sandbox.snapshot(wait_durable=True)
print(snapshot.id)

The original sandbox keeps running. wait_durable=True waits until the snapshot has finished saving and can be used if the original sandbox becomes unavailable. Restore that snapshot into a new sandbox:

restored = box.snapshots.restore(snapshot.id)
print(restored.id)
print(restored.files.read("/work/result.txt"))

The restored sandbox has its own ID and uses the snapshot’s CPU and memory configuration; those cannot change during restore. The writable disk is the one setting that can — see Grow the writable disk below. Changes made after the snapshot are not included, and changes to the restored copy do not change the original. A snapshot of a sandbox with datasets restores with the same datasets mounted. Only your organization can restore it, and only while each dataset is still granted to your organization at the same version; otherwise the restore returns 403. Forks inherit the parent’s datasets in the same way.

Grow the writable disk

A sandbox that is running out of disk does not need to start over. Snapshot it, then restore the snapshot at a larger size:

snapshot = sandbox.snapshot(wait_durable=True)
bigger = box.snapshots.restore(snapshot.id, writable_size_bytes=32 * 2**30)

The restored sandbox keeps every file and running process from the snapshot and sees the larger disk immediately — no formatting or in-guest steps. Three rules apply:

Sizes come from a fixed set: 16 GiB (the default) or 32 GiB — 64 GiB on upgraded plans. Any other value returns 400.
Disks grow, never shrink. Restoring a snapshot at a size smaller than it was captured with returns 400.
Fork accepts no size. Fork copies inherit the parent’s disk exactly; to get larger children, snapshot the parent, restore it at the larger size, and fork the restored sandbox. Passing writable_size_bytes to a fork returns 400 explaining exactly that.

Omitting writable_size_bytes on a restore keeps the snapshot’s own size, so existing code is unaffected.

Check an existing snapshot

You can create a snapshot without waiting for durability, then check it later:

checkpoint = sandbox.snapshot()
checkpoint = box.snapshots.wait_durable(checkpoint.id)
print(checkpoint.durable)

A snapshot may be restorable before it is durable. Wait for durability before deleting the original sandbox or relying on the checkpoint for recovery. If a wait times out, check the snapshot again; the wait ending does not cancel saving. Find snapshots in Console → Snapshots or with box.snapshots.list(). To save a checkpoint and let the original sandbox rest immediately, use snapshot(leave_asleep=True, wait_durable=True). Its next command or file access wakes it automatically; there is nothing to call first.

Fork for parallel work

Create an independent copy of the current sandbox:

child = sandbox.fork()
child.run("printf 'Alternative result\n' > /work/result.txt").check()
print(sandbox.files.read("/work/result.txt"))
child.delete()

The original still contains First result. To create several copies from the same point, request them together:

children = sandbox.fork(n=4)
try:
    for child in children:
        print(child.id)
finally:
    for child in children:
        child.delete()

fork() returns one sandbox. Passing n returns a list, including when n=1. You can create up to 16 copies per call, within your organization’s sandbox limit. Fork between commands whenever possible. Copies inherit running processes and connection state, so reconnect external services separately in each copy before using them. Avoid copying a process that is partway through an external write.

See what changed

Compare any two snapshots to see what changed between them, from files and SQLite rows to processes and memory:

before = sandbox.snapshot()
sandbox.run("pip install -q requests && echo done > /work/status").check()
after = sandbox.snapshot()

changes = box.snapshots.diff(before, after, content=True)
for f in changes["files"][:10]:
    print(f["change"], f["path"])

The diff is read from the snapshots, not from a running sandbox, so it works after the sandbox is deleted and between snapshots of different sandboxes. Taking a snapshot after every step of an agent’s work lets you find the step that changed something: compare each step with the one before it.

Merge work back

Merge brings the file changes from one snapshot into a running sandbox. A typical use is to fork, work in the copy, and merge the result back:

base = sandbox.snapshot()
child = box.snapshots.restore(base.id)
child.run("pip install -q requests").check()
work = child.snapshot()

plan = sandbox.merge(work, base, dry_run=True)
print(plan["conflicts"])
report = sandbox.merge(work, base, on_conflict="skip")
print(report["applied"], report.get("pre_merge_snapshot_id"))

A path that both sides changed differently is a conflict. Files merge whole: a merge does not combine edits inside one file, and a SQLite database is one file. Merge carries files only, not memory or running processes. To undo a merge, restore pre_merge_snapshot_id.

Clean up

Snapshots remain after you delete their original sandbox. Delete each resource when you no longer need it:

restored.delete()
sandbox.delete()
box.snapshots.delete(snapshot.id)
box.snapshots.delete(checkpoint.id)
box.close()

To download a snapshot’s files outside LithosBox, see Snapshots and exports.

Getting Started

Reference

Guides

Save, restore, fork

Save and restore

Grow the writable disk

Check an existing snapshot

Fork for parallel work

See what changed

Merge work back

Clean up

​Save and restore

​Grow the writable disk

​Check an existing snapshot

​Fork for parallel work

​See what changed

​Merge work back

​Clean up

Save and restore

Grow the writable disk

Check an existing snapshot

Fork for parallel work

See what changed

Merge work back

Clean up