Add docs for snapshots (#2877)

Author: ry

sandbox/_data.ts

@@ -35,7 +35,7 @@ export const sidebar = [
         href: "/sandbox/apps/",
       },
       {
-        title: "Volumes",
+        title: "Volumes & Snapshots",
         href: "/sandbox/volumes/",
       },
       {

sandbox/cli.md

@@ -257,35 +257,26 @@ deno sandbox volumes delete my-volume
 
 ## Managing snapshots
 
-Snapshots allow you to preserve the current state of a volume as a point-in-time
-copy.
+Snapshots are read-only images created from volumes. Use them to pre-install
+software once, then boot new sandboxes instantly with everything ready. See
+[Volumes & Snapshots](./volumes/) for the full workflow.
 
 ### Creating snapshots
 
-Create a new snapshot from an existing volume:
+Create a snapshot from an existing volume:
 
 ```bash
 deno sandbox snapshots create my-volume my-snapshot
 ```
 
-You can also use the `volumes snapshot` command:
-
-```bash
-deno sandbox volumes snapshot my-volume my-snapshot
-```
-
 ### Listing snapshots
 
 List all snapshots in your organization:
 
 ```bash
-deno sandbox snapshots list
-```
-
-You can also search for specific snapshots:
-
-```bash
-deno sandbox snapshots list my-snapshot
+$ deno sandbox snapshots list
+ID                             SLUG          REGION   ALLOCATED    BOOTABLE
+snp_ord_spmbe47dysccpy277ma6   my-snapshot   ord      217.05 MiB   TRUE
 ```
 
 ### Deleting snapshots

sandbox/volumes.md

@@ -1,21 +1,24 @@
 ---
-title: "Persistent Volumes"
-description: "Mount block storage into Deno Sandbox to keep state between sessions"
+title: "Volumes & Snapshots"
+description: "Persistent storage and bootable images for Deno Sandbox"
 ---
 
+Deno Sandbox provides two storage primitives:
+
+- **Volumes** – read-write block storage. Use for caches, databases, and
+  artifacts that persist across sessions.
+- **Snapshots** – read-only images created from volumes. Use for pre-installing
+  software so sandboxes boot instantly with everything ready. You can also
+  create new volumes from snapshots.
+
+## Volumes
+
 Persistent volumes let you attach regional block storage to a sandbox so data
 survives process restarts and new connections. They are ideal for package
 caches, build artifacts, SQLite databases, or any workflow that needs a small
 amount of durable storage without promoting code to a full Deno Deploy app.
 
-:::note
-
-Persistent volumes are currently in private beta. Contact
-[support](mailto:support@deno.com) to request access to this feature
-
-:::
-
-## Provision storage
+### Provision storage
 
 <deno-tabs group-id="sandbox-sdk">
 <deno-tab value="js" label="JavaScript" default>
@@ -98,7 +101,7 @@ print(volume)
 | `region`   | ✅       | Must match an available sandbox region (`"ord"` or `"ams"` today). Only sandboxes in the same region can mount the volume. |
 | `capacity` | ✅       | Between 300 MB and 20 GB. Pass a number of bytes or a string with `GB/MB/KB` (decimal) or `GiB/MiB/KiB` (binary) units.    |
 
-## Inspect and search volumes
+### Inspect and search volumes
 
 The volumes API returns paginated results and can fetch a single record by slug
 or UUID.
@@ -108,38 +111,33 @@ or UUID.
 
 ```tsx
 const page = await client.volumes.list({ search: "training" });
-for (const info of page.items) {
-  console.log(
-    info.slug,
-    formatBytes(info.used),
-    "of",
-    formatBytes(info.capacity),
-  );
+for (const vol of page.items) {
+  console.log(vol.slug, vol.used, vol.capacity);
 }
 
-const latest = await client.volumes.get("training-cache");
+const vol = await client.volumes.get("training-cache");
 ```
 
 </deno-tab>
 <deno-tab value="python" label="Python">
 
 ```py
 page = sdk.volumes.list(search="training")
-for info in page.items:
-  print(f"{info['slug']} {info['used']} of {info['capacity']}")
+for vol in page.items:
+  print(f"{vol['slug']} {vol['used']} {vol['capacity']}")
 
-latest = sdk.volumes.get("training-cache")
+vol = sdk.volumes.get("training-cache")
 ```
 
 </deno-tab>
 <deno-tab value="python-async" label="Python (Async)">
 
 ```py
 page = await sdk.volumes.list(search="training")
-async for info in page:
-  print(f"{info['slug']} {info['used']} of {info['capacity']}")
+async for vol in page:
+  print(f"{vol['slug']} {vol['used']} {vol['capacity']}")
 
-latest = await sdk.volumes.get("training-cache")
+vol = await sdk.volumes.get("training-cache")
 ```
 
 </deno-tab>
@@ -149,11 +147,18 @@ The `used` field reports the most recent estimate the control plane received
 from the underlying cluster. It can lag a few minutes behind reality, so always
 size volumes with headroom.
 
-## Mount volumes inside a sandbox
+### Mount volumes inside a sandbox
+
+Pass a `volumes` mapping when creating a sandbox. Keys are mount paths and
+values are either the volume slug or ID. The sandbox and volume **must be in the
+same region**.
+
+:::note
 
-Pass a volumes mapping when creating a sandbox. Keys are mount paths and values
-are either the volume slug or ID. The sandbox and volume **must live in the same
-region**.
+`Sandbox.create()` and `client.sandboxes.create()` are equivalent—use whichever
+fits your code style.
+
+:::
 
 <deno-tabs group-id="sandbox-sdk">
 <deno-tab value="js" label="JavaScript" default>
@@ -271,7 +276,7 @@ async with sdk.sandbox.create(
 Mounts behave like regular directories. You can create subfolders, write binary
 files, or execute programs directly from the volume.
 
-## Delete volumes safely
+### Delete volumes safely
 
 <deno-tabs group-id="sandbox-sdk">
 <deno-tab value="js" label="JavaScript" default>
@@ -306,3 +311,167 @@ Deletion is a two-step process:
    was removed accidentally.
 
 During the grace period you cannot mount or read the volume.
+
+## Snapshots
+
+Snapshots are read-only images created from volumes. When a sandbox boots with a
+snapshot as its root, the entire filesystem is replaced with the snapshot
+contents. Run `apt-get install` or `npm install` once, snapshot the result, and
+every future sandbox starts instantly with everything already installed.
+
+### Creating a snapshot
+
+The workflow is:
+
+1. Create a **bootable volume** from a base image
+2. Boot a sandbox with that volume as `root` (writable)
+3. Install software
+4. Snapshot the volume
+
+Sandboxes booted from the snapshot start instantly with everything installed.
+
+A volume is **bootable** when created with the `from` option. Currently
+`builtin:debian-13` is the only available base image.
+
+<deno-tabs group-id="sandbox-sdk">
+<deno-tab value="js" label="JavaScript" default>
+
+```tsx
+import { Client } from "@deno/sandbox";
+
+const client = new Client();
+
+// 1. Create a bootable volume
+const volume = await client.volumes.create({
+  region: "ord",
+  slug: "my-toolchain",
+  capacity: "10GiB",
+  from: "builtin:debian-13",
+});
+
+// 2. Boot a sandbox with the volume as root (writable)
+await using sandbox = await client.sandboxes.create({
+  region: "ord",
+  root: volume.slug,
+});
+
+// 3. Install software
+await sandbox.sh`apt-get update && apt-get install -y nodejs npm`;
+await sandbox.sh`npm install -g typescript`;
+
+// 4. Snapshot the volume
+const snapshot = await client.volumes.snapshot(volume.id, {
+  slug: "my-toolchain-snapshot",
+});
+```
+
+</deno-tab>
+<deno-tab value="cli" label="CLI">
+
+```bash
+# Create snapshot from a volume
+deno sandbox snapshots create my-toolchain my-toolchain-snapshot
+```
+
+</deno-tab>
+</deno-tabs>
+
+### Booting from a snapshot
+
+Once you have a snapshot, use it as the `root` when creating new sandboxes. The
+sandbox must be created in the same region as the snapshot:
+
+<deno-tabs group-id="sandbox-sdk">
+<deno-tab value="js" label="JavaScript" default>
+
+```tsx
+await using sandbox = await client.sandboxes.create({
+  region: "ord",
+  root: "my-toolchain-snapshot", // snapshot slug or ID
+});
+
+// TypeScript and Node.js are already installed
+await sandbox.sh`tsc --version`;
+await sandbox.sh`node --version`;
+```
+
+</deno-tab>
+</deno-tabs>
+
+The sandbox boots with the snapshot's filesystem as its root. Any writes during
+the session are ephemeral—they don't modify the snapshot.
+
+### Listing snapshots
+
+<deno-tabs group-id="sandbox-sdk">
+<deno-tab value="js" label="JavaScript" default>
+
+```tsx
+const page = await client.snapshots.list();
+for (const snap of page.items) {
+  console.log(snap.slug, snap.region, snap.bootable);
+}
+```
+
+</deno-tab>
+<deno-tab value="cli" label="CLI">
+
+```bash
+$ deno sandbox snapshots list
+ID                             SLUG                    REGION   ALLOCATED    BOOTABLE
+snp_ord_spmbe47dysccpy277ma6   my-toolchain-snapshot   ord      217.05 MiB   TRUE
+```
+
+</deno-tab>
+</deno-tabs>
+
+### Creating a volume from a snapshot
+
+Create a new writable volume from a snapshot:
+
+<deno-tabs group-id="sandbox-sdk">
+<deno-tab value="js" label="JavaScript" default>
+
+```tsx
+const volume = await client.volumes.create({
+  region: "ord",
+  slug: "my-toolchain-fork",
+  capacity: "10GiB",
+  from: "my-toolchain-snapshot",
+});
+```
+
+</deno-tab>
+</deno-tabs>
+
+The new volume contains the snapshot's contents and is fully writable. Use this
+to modify a snapshot's contents, then snapshot again.
+
+### Deleting snapshots
+
+<deno-tabs group-id="sandbox-sdk">
+<deno-tab value="js" label="JavaScript" default>
+
+```tsx
+await client.snapshots.delete("my-toolchain-snapshot");
+```
+
+</deno-tab>
+<deno-tab value="cli" label="CLI">
+
+```bash
+deno sandbox snapshots delete my-toolchain-snapshot
+```
+
+</deno-tab>
+</deno-tabs>
+
+### Volumes vs Snapshots
+
+| Feature        | Volumes                             | Snapshots                          |
+| -------------- | ----------------------------------- | ---------------------------------- |
+| Access         | Read-write                          | Read-only                          |
+| Mount point    | Any path, or root if bootable       | Root filesystem only               |
+| Use case       | Caches, databases, install software | Pre-installed software, toolchains |
+| Concurrent use | One sandbox at a time               | Many sandboxes simultaneously      |
+| Region         | Must match sandbox region           | Must match sandbox region          |