docs: add snapshot, suspend & resume example

Author: james-rl

EXAMPLES.md

@@ -10,6 +10,7 @@ Runnable examples live in [`examples/`](./examples).
 - [Blueprint with Build Context](#blueprint-with-build-context)
 - [Devbox From Blueprint (Run Command, Shutdown)](#devbox-from-blueprint-lifecycle)
 - [Devbox Snapshot and Resume](#devbox-snapshot-resume)
+- [Devbox Snapshots (Suspend, Resume, Restore, Delete)](#devbox-snapshots)
 - [Devbox Tunnel (HTTP Server Access)](#devbox-tunnel)
 - [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
 - [Secrets with Devbox (Create, Inject, Verify, Delete)](#secrets-with-devbox)
@@ -106,6 +107,37 @@ uv run pytest -m smoketest tests/smoketests/examples/
 
 **Source:** [`examples/devbox_snapshot_resume.py`](./examples/devbox_snapshot_resume.py)
 
+<a id="devbox-snapshots"></a>
+## Devbox Snapshots (Suspend, Resume, Restore, Delete)
+
+**Use case:** Upload a file to a devbox, preserve it across suspend and resume, create a disk snapshot, restore multiple devboxes from that snapshot, mutate each copy independently, and delete the snapshot when finished.
+
+**Tags:** `devbox`, `snapshot`, `suspend`, `resume`, `files`, `cleanup`
+
+### Workflow
+- Create a source devbox
+- Upload a file and mutate it into a shared baseline
+- Suspend and resume the source devbox
+- Create a disk snapshot from the resumed devbox
+- Restore two additional devboxes from the same snapshot baseline
+- Mutate the same file differently in each devbox to prove isolation
+- Shutdown the devboxes and delete the snapshot
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.devbox_snapshots
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/devbox_snapshots.py`](./examples/devbox_snapshots.py)
+
 <a id="devbox-tunnel"></a>
 ## Devbox Tunnel (HTTP Server Access)
 

README.md

@@ -91,6 +91,7 @@ Functionality between the synchronous and asynchronous clients is otherwise iden
 ## Examples
 
 Workflow-oriented runnable examples are documented in [`EXAMPLES.md`](./EXAMPLES.md).
+For a suspend/resume plus shared snapshot restore workflow, see [`examples/devbox_snapshots.py`](./examples/devbox_snapshots.py).
 
 `EXAMPLES.md` is generated from metadata in `examples/*.py` and should not be edited manually.
 Regenerate it with:

examples/registry.py

@@ -9,6 +9,7 @@
 
 from .devbox_tunnel import run_devbox_tunnel_example
 from .example_types import ExampleResult
+from .devbox_snapshots import run_devbox_snapshots_example
 from .mcp_github_tools import run_mcp_github_tools_example
 from .secrets_with_devbox import run_secrets_with_devbox_example
 from .devbox_snapshot_resume import run_devbox_snapshot_resume_example
@@ -39,6 +40,13 @@
         "required_env": ["RUNLOOP_API_KEY"],
         "run": run_devbox_snapshot_resume_example,
     },
+    {
+        "slug": "devbox-snapshots",
+        "title": "Devbox Snapshots (Suspend, Resume, Restore, Delete)",
+        "file_name": "devbox_snapshots.py",
+        "required_env": ["RUNLOOP_API_KEY"],
+        "run": run_devbox_snapshots_example,
+    },
     {
         "slug": "devbox-tunnel",
         "title": "Devbox Tunnel (HTTP Server Access)",

llms.txt

@@ -11,6 +11,7 @@
 ## Core Patterns
 
 - [Devbox lifecycle example](examples/devbox_from_blueprint_lifecycle.py): Create blueprint, launch devbox, run commands, cleanup
+- [Devbox snapshots example](examples/devbox_snapshots.py): Suspend and resume a devbox, create a shared snapshot baseline, restore multiple devboxes, verify isolation, cleanup
 - [Devbox snapshot and resume example](examples/devbox_snapshot_resume.py): Snapshot disk, resume from snapshot, verify state isolation
 - [MCP GitHub example](examples/mcp_github_tools.py): MCP Hub integration with Claude Code
 - [Secrets with Devbox example](examples/secrets_with_devbox.py): Create secret, inject into devbox, verify, cleanup