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:

The workspace must be stopped (not running)
Rigbox copies the workspace’s root filesystem image
The snapshot is stored with sparse file optimization (only non-zero blocks are saved)
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:

rig workspace stop --workspace {workspace_id}

Step 2 - Create the snapshot:

rig snapshot create --workspace {workspace_id} --name before-migration

This prints the new snapshot’s id (e.g. snap_abc123) and size_bytes. 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

rig snapshot ls --workspace {workspace_id}

The JSON form (--output json) returns:

[
  {
    "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, omit the --workspace filter:

rig snapshot ls

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
rig snapshot restore --workspace {workspace_id} --snapshot {snapshot_id}

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:

rig workspace start --workspace {workspace_id}

Delete a Snapshot

rig snapshot rm --workspace {workspace_id} --snapshot {snapshot_id}

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 Size	Typical Snapshot Size	Why
5 GB	2-3 GB	OS and packages use ~2 GB, rest is empty space
10 GB	3-5 GB	More data, but still sparse
20 GB	5-10 GB	Depends 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
rig workspace stop --workspace ws_demo
rig snapshot create --workspace ws_demo --name pre-demo-2026-04-07
rig workspace start --workspace ws_demo

# ... run the demo ...

# Something went wrong - restore and try again
rig workspace stop --workspace ws_demo
rig snapshot restore --workspace ws_demo --snapshot snap_predemo
rig workspace start --workspace ws_demo

Experiment Branching

Try a risky change without fear. Snapshot first, experiment freely, restore if it fails.

# Checkpoint current state
rig workspace stop --workspace ws_ml
rig snapshot create --workspace ws_ml --name stable-model-v2
rig workspace start --workspace ws_ml

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

rig workspace stop --workspace ws_ml
rig snapshot restore --workspace ws_ml --snapshot snap_stable_v2
rig workspace start --workspace ws_ml
# 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
rig workspace stop --workspace "$WORKSPACE_ID"
rig snapshot create --workspace "$WORKSPACE_ID" --name "daily-backup-$DATE"
rig workspace start --workspace "$WORKSPACE_ID"

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. rig workspace stop and rig workspace start poll status internally, so there’s no manual wait loop.

WS_ID="ws_abc123"

# Workflow: checkpoint -> experiment -> restore
rig workspace stop --workspace "$WS_ID"
SNAP_ID=$(rig snapshot create --workspace "$WS_ID" --name before-experiment --output json | jq -r .id)
rig workspace start --workspace "$WS_ID"

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

# Something went wrong - roll back
rig workspace stop --workspace "$WS_ID"
rig snapshot restore --workspace "$WS_ID" --snapshot "$SNAP_ID"
rig workspace start --workspace "$WS_ID"
# 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

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

How Snapshots Work

Create a Snapshot

List Snapshots

For a Specific Workspace

All Your Snapshots

Restore a Snapshot

Delete a Snapshot

Storage and Sizing

Use Cases

Pre-Demo Checkpoint

Experiment Branching

Disaster Recovery

Reproducibility

Complete Workflow Example

Limitations

Next Steps

​How Snapshots Work

​Create a Snapshot

​List Snapshots

​For a Specific Workspace

​All Your Snapshots

​Restore a Snapshot

​Delete a Snapshot

​Storage and Sizing

​Use Cases

​Pre-Demo Checkpoint

​Experiment Branching

​Disaster Recovery

​Reproducibility

​Complete Workflow Example

​Limitations

​Next Steps

How Snapshots Work

Create a Snapshot

List Snapshots

For a Specific Workspace

All Your Snapshots

Restore a Snapshot

Delete a Snapshot

Storage and Sizing

Use Cases

Pre-Demo Checkpoint

Experiment Branching

Disaster Recovery

Reproducibility

Complete Workflow Example

Limitations

Next Steps