Snapshots

A snapshot captures a sandbox’s disk state. It is identified by a snapshot_id and tied to the source_sandbox_id it was taken from. Its identity outlives the source: you can delete the sandbox that produced a snapshot and keep the snapshot. Snapshots are part of the public REST API (/v1/sandbox/{sandbox_id}/snapshots and /v1/snapshot/{snapshot_id}), the SDKs, the CLI and the MCP server.

Creating a snapshot

The source sandbox must be running. A paused, failed, or deleted sandbox is rejected rather than snapshotted.

curl -X POST https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/snapshots \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "baseline"}'

snapshot = sandbox.snapshot(name="baseline")

const snapshot = await sandbox.snapshot({ name: "baseline" });

snapshot, err := client.CreateSnapshot(ctx, sandbox.ID, bonya.SnapshotOptions{
	IdempotencyKey: "example-snapshot-1",
})

bonya snapshot create web

Create accepts an idempotency key, so a retried call returns the same snapshot rather than minting a second one. See Idempotency.

Restoring and forking

Start a new sandbox from a snapshot by passing its id to create:

restored = client.create_sandbox(snapshot=snapshot.id)

const restored = await client.createSandbox({ snapshot: snapshot.id });

To clone a running sandbox without naming a snapshot, fork it: POST /v1/sandbox/{sandbox_id}/fork with {"count": 2}, or sandbox.fork(2) in the SDKs.

Listing and deleting

GET /v1/sandbox/{sandbox_id}/snapshots lists a sandbox’s snapshots, GET /v1/snapshot/{snapshot_id} fetches one, and DELETE /v1/snapshot/{snapshot_id} removes it.

snapshots = sandbox.list_snapshots()
snapshot.delete()

const snapshots = await sandbox.listSnapshots();
await snapshot.delete();

bonya snapshot delete web <snapshot-id>

Delete is idempotent in the SDKs: calling it again on an already-deleted snapshot is a no-op.

Get started

Tutorials

Core concepts

API essentials

Guides

Creating a snapshot

Restoring and forking

Listing and deleting

Sandboxes

Snapshot CLI reference

​Creating a snapshot

​Restoring and forking

​Listing and deleting

​Related

Sandboxes

Snapshot CLI reference

Creating a snapshot

Restoring and forking

Listing and deleting

Related