Skip to main content

​
Snapshots

Snapshots capture the full disk state of a workspace — every file, installed package, database, and configuration. You can use them to checkpoint your work, experiment safely, or recover from mistakes.

​
How Snapshots Work

A snapshot is a point-in-time copy of a workspace’s entire filesystem. When you create a snapshot:
  1. The workspace must be stopped (not running)
  2. Rigbox copies the workspace’s root filesystem image
  3. The snapshot is stored with sparse file optimization (only non-zero blocks are saved)
  4. You can restore the snapshot at any time to roll back the workspace to that exact state
Snapshots capture disk state only — they do not capture running processes or in-memory state. Stop your workspace cleanly (let services shut down gracefully) before snapshotting.

​
Create a Snapshot

Stop the workspace first, then create a named snapshot. Step 1 — Stop the workspace: 
curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/stop \
  -H "Authorization: Bearer $RIGBOX_TOKEN"
Step 2 — Create the snapshot: 
curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/snapshots \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "before-migration"
  }'
See the Create Snapshot API reference for the full response schema.
Creating a snapshot while a workspace is running will return an error. Always stop the workspace first.

​
List Snapshots

​
For a Specific Workspace

curl -s https://api.rigbox.dev/api/workspaces/{workspace_id}/snapshots \
  -H "Authorization: Bearer $RIGBOX_TOKEN" | jq .

[
  {
    "id": "snap_abc123",
    "workspace_id": "ws_xyz789",
    "name": "before-migration",
    "size_bytes": 2147483648,
    "created_at": "2026-04-07T10:30:00Z"
  },
  {
    "id": "snap_def456",
    "workspace_id": "ws_xyz789",
    "name": "after-setup",
    "size_bytes": 1073741824,
    "created_at": "2026-04-06T15:00:00Z"
  }
]

​
All Your Snapshots

To see snapshots across all your workspaces: 
curl -s https://api.rigbox.dev/api/snapshots \
  -H "Authorization: Bearer $RIGBOX_TOKEN" | jq .
See the List Snapshots API reference for pagination and filtering options.

​
Restore a Snapshot

Restoring a snapshot replaces the workspace’s current disk state with the snapshot’s saved state. 
# Workspace must be stopped
curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/snapshots/{snapshot_id}/restore \
  -H "Authorization: Bearer $RIGBOX_TOKEN"
Restoring a snapshot overwrites the current workspace disk state. Any changes made since the snapshot was taken will be lost. If you want to keep the current state, create a new snapshot before restoring.
After restoring, start the workspace to boot into the restored state: 
curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/start \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

​
Delete a Snapshot

curl -X DELETE https://api.rigbox.dev/api/workspaces/{workspace_id}/snapshots/{snapshot_id} \
  -H "Authorization: Bearer $RIGBOX_TOKEN"
Deleting a snapshot is permanent and frees the associated storage. This does not affect the workspace itself.

​
Storage and Sizing

Snapshots use sparse file optimization. This means only disk blocks that actually contain data are stored — empty space is not copied.
Workspace Disk SizeTypical Snapshot SizeWhy
5 GB2-3 GBOS and packages use ~2 GB, rest is empty space
10 GB3-5 GBMore data, but still sparse
20 GB5-10 GBDepends on how much data you have stored
The actual size depends on how much data is written to the filesystem. A workspace with a 10 GB disk but only 3 GB of actual files will produce a snapshot close to 3 GB.
Check the size_bytes field in the snapshot response to see the actual storage used.

​
Use Cases

​
Pre-Demo Checkpoint

Snapshot before a live demo so you can instantly roll back if something breaks. 
# Before the demo
curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/stop \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/snapshots \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-demo-2026-04-07"}'

curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/start \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

# ... run the demo ...

# Something went wrong — restore and try again
curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/stop \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/snapshots/snap_predemo/restore \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_demo/start \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

​
Experiment Branching

Try a risky change without fear. Snapshot first, experiment freely, restore if it fails. 
# Checkpoint current state
curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/stop \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/snapshots \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "stable-model-v2"}'

curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/start \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

# ... experiment with new model architecture ...
# ... results are worse, roll back ...

curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/stop \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/snapshots/snap_stable_v2/restore \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST https://api.rigbox.dev/api/workspaces/ws_ml/start \
  -H "Authorization: Bearer $RIGBOX_TOKEN"
# Back to the known-good state

​
Disaster Recovery

Create regular snapshots as backups for critical workspaces. 
#!/bin/bash
# Run this on a schedule (e.g., daily via cron)
WORKSPACE_ID="ws_production"
DATE=$(date +%Y-%m-%d)

# Stop, snapshot, start
curl -X POST "https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/stop" \
  -H "Authorization: Bearer $RIGBOX_TOKEN"

curl -X POST "https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/snapshots" \
  -H "Authorization: Bearer $RIGBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"daily-backup-$DATE\"}"

curl -X POST "https://api.rigbox.dev/api/workspaces/$WORKSPACE_ID/start" \
  -H "Authorization: Bearer $RIGBOX_TOKEN"
If you automate snapshots, consider cleaning up old ones periodically to manage storage. Keep the last N snapshots and delete older ones.

​
Reproducibility

Share a known-good workspace state with your team. Create a snapshot at a stable point, and teammates can restore from it to start from the exact same environment.

​
Complete Workflow Example

Here is a full checkpoint-and-restore flow using Python. 
import requests
import time

BASE = "https://api.rigbox.dev/api"
HEADERS = {"Authorization": f"Bearer {token}"}
WS_ID = "ws_abc123"


def stop_workspace():
    """Stop the workspace and wait for it to be fully stopped."""
    requests.post(f"{BASE}/workspaces/{WS_ID}/stop", headers=HEADERS)
    # Poll until stopped
    while True:
        r = requests.get(f"{BASE}/workspaces/{WS_ID}", headers=HEADERS)
        if r.json()["status"] == "stopped":
            break
        time.sleep(2)


def start_workspace():
    """Start the workspace."""
    requests.post(f"{BASE}/workspaces/{WS_ID}/start", headers=HEADERS)


def create_snapshot(name: str) -> str:
    """Create a snapshot and return its ID."""
    r = requests.post(
        f"{BASE}/workspaces/{WS_ID}/snapshots",
        headers=HEADERS,
        json={"name": name}
    )
    return r.json()["id"]


def restore_snapshot(snapshot_id: str):
    """Restore a snapshot."""
    requests.post(
        f"{BASE}/workspaces/{WS_ID}/snapshots/{snapshot_id}/restore",
        headers=HEADERS
    )


# Workflow: checkpoint -> experiment -> restore
stop_workspace()
snap_id = create_snapshot("before-experiment")
start_workspace()

# ... make changes, run experiments ...

# Something went wrong — roll back
stop_workspace()
restore_snapshot(snap_id)
start_workspace()
# Back to the checkpointed state

​
Limitations

  • Workspace must be stopped — you cannot snapshot or restore a running workspace
  • Disk state only — running processes and in-memory data are not captured
  • Same workspace only — you cannot restore a snapshot from workspace A into workspace B
  • Storage costs — snapshots consume storage proportional to their size; clean up old snapshots you no longer need

​
Next Steps

  • Setup Scripts — automate the setup that leads to a snapshot-worthy state
  • Service Specs — define services that auto-start after a snapshot restore
  • Bring Your Own Keys — configure AI providers for workspaces you snapshot