feat(snapshot): add backend-neutral cloud snapshots

Route snapshot lifecycle through backend-specific implementations and add cloud snapshot contracts and restore support.

Preserve typed snapshot references across SDKs, add instance archive export parity, and update tests and documentation.

Author: toksdotdev

crates/cli/lib/commands/self_cmd.rs

@@ -1104,11 +1104,12 @@ async fn run_downgrade_with_db(
                 && ctx.operation.phase() < DowngradePhase::ArtifactsReverted
             {
                 let spinner = ui::Spinner::start("Checking", "retained snapshot graph");
-                let result = microsandbox::snapshot::downgrade::preflight_managed_v066(
-                    ctx.db.inner(),
-                    ctx.snapshots_dir,
-                )
-                .await;
+                let result =
+                    microsandbox::backend::local_snapshot_downgrade::preflight_managed_v066(
+                        ctx.db.inner(),
+                        ctx.snapshots_dir,
+                    )
+                    .await;
                 match result {
                     Ok(plan) => {
                         spinner.finish_success("Checked");
@@ -1175,7 +1176,7 @@ async fn run_downgrade_with_db(
                     .set_phase(DowngradePhase::ArtifactsReverting)?;
                 if let Some(plan) = snapshot_plan {
                     let spinner = ui::Spinner::start("Reverting", "snapshot artifacts");
-                    match microsandbox::snapshot::downgrade::execute_managed_v066(
+                    match microsandbox::backend::local_snapshot_downgrade::execute_managed_v066(
                         ctx.db.inner(),
                         ctx.operation.recovery_dir(),
                         plan,

crates/cli/lib/commands/snapshot.rs

@@ -1,7 +1,7 @@
 //! `msb snapshot` command — manage disk snapshots.
 
 use clap::{Args, Subcommand};
-use microsandbox::Snapshot;
+use microsandbox::{Snapshot, SnapshotReference};
 
 use crate::ui;
 
@@ -225,7 +225,7 @@ async fn create(args: SnapshotCreateArgs) -> anyhow::Result<()> {
             spinner.finish_success("Snapshotted");
             if !args.quiet {
                 println!("{}", snap.digest());
-                println!("{}", snap.path().display());
+                println!("{}", format_reference(&snap.reference()));
             }
             Ok(())
         }
@@ -259,7 +259,8 @@ async fn list(args: SnapshotListArgs) -> anyhow::Result<()> {
                     "migration_state": s.migration_state(),
                     "migration_error_code": s.migration_error_code(),
                     "created_at": ui::format_json_datetime(&s.created_at().and_utc()),
-                    "artifact_path": s.path().display().to_string(),
+                    "reference": format_reference(&s.reference()),
+                    "reference_kind": s.reference().kind(),
                 })
             })
             .collect();
@@ -315,7 +316,7 @@ async fn inspect(args: SnapshotInspectArgs) -> anyhow::Result<()> {
     let m = snap.manifest();
 
     ui::detail_kv("Digest", snap.digest());
-    ui::detail_kv("Path", &snap.path().display().to_string());
+    ui::detail_kv("Reference", &format_reference(&snap.reference()));
     ui::detail_kv("Image", &m.image.reference);
     ui::detail_kv("Image Manifest", &m.image.manifest_digest);
     ui::detail_kv("Scope", format_scope(m.scope));
@@ -427,7 +428,7 @@ async fn save(args: SnapshotSaveArgs) -> anyhow::Result<()> {
 async fn load(args: SnapshotLoadArgs) -> anyhow::Result<()> {
     let handle = Snapshot::load(&args.archive, args.dest.as_deref()).await?;
     println!("{}", handle.digest());
-    println!("{}", handle.path().display());
+    println!("{}", format_reference(&handle.reference()));
     Ok(())
 }
 
@@ -449,6 +450,10 @@ fn format_scope(scope: microsandbox::SnapshotScope) -> &'static str {
     }
 }
 
+fn format_reference(reference: &SnapshotReference) -> String {
+    reference.value().to_string()
+}
+
 fn format_size(bytes: u64) -> String {
     const KIB: u64 = 1024;
     const MIB: u64 = KIB * 1024;

docs/sandboxes/snapshots.mdx

@@ -4,14 +4,22 @@ description: Capture a sandbox's writable layer as a portable artifact
 icon: "code-branch"
 ---
 
-<Tooltip tip="Disk snapshots are local-only. On microsandbox cloud, use a named volume for state that must survive sandbox replacement."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
-
-A snapshot is a portable, on-disk capture of a sandbox's writable filesystem. Move it with `scp`, archive it as `.tar.zst`, or boot fresh sandboxes from it.
+A snapshot captures a sandbox's writable filesystem. The local backend stores a
+portable on-disk artifact; microsandbox cloud stores it in managed object
+storage by default, or in a directory on the organization's host volume when a
+destination is supplied.
 
 <Note>
 Snapshots are **disk-only** and require a sandbox that is not running. Stopped and crashed sandboxes can be snapshotted; running, draining, and paused sandboxes are rejected.
 </Note>
 
+<Note>
+Snapshot objects now expose a backend-neutral `reference` (and reference kind)
+instead of a host `path` or storage `location`. When upgrading, pass the
+snapshot object directly where supported, or pass its reference to the restore
+API. This keeps the same application code valid for local and cloud backends.
+</Note>
+
 ## What gets captured
 
 | Captured | Not captured |
@@ -41,20 +49,26 @@ msb run --name worker --from-snapshot after-pip-install \
 ```
 
 <Tip>
-By default, the snapshot lives at `~/.microsandbox/snapshots/after-pip-install/`. That whole directory is the snapshot.
+On the local backend, the snapshot lives at
+`~/.microsandbox/snapshots/after-pip-install/`. In cloud, omitting a destination
+creates a managed snapshot and returns its stable snapshot reference.
 </Tip>
 
 ## Snapshot a sandbox
 
-Snapshot under a bare name, resolved to `~/.microsandbox/snapshots/<name>/` by default. The name is the snapshot's identity; pass a destination directory to create the artifact on a different volume (`DIR/<name>`). Either way the directory is the whole artifact; move it with save/load (or plain `mv`):
+Snapshot under a bare name. Locally, it resolves to
+`~/.microsandbox/snapshots/<name>/`. In cloud, it is uploaded to managed storage
+and recorded by the control plane. Passing a destination stores an artifact at
+`DIR/<name>` locally or at the corresponding path on the organization's host
+volume in cloud.
 
 <CodeGroup>
 ```rust Rust
 use microsandbox::Sandbox;
 
 let h = Sandbox::get("baseline").await?;
 
-// Resolves under ~/.microsandbox/snapshots/<name>/
+// Local: default store. Cloud: managed snapshot storage.
 let snap = h.snapshot("after-pip-install").await?;
 
 println!("{}", snap.digest()); // sha256:...
@@ -65,7 +79,7 @@ import { Sandbox } from "microsandbox";
 
 const h = await Sandbox.get("baseline");
 
-// Resolves under ~/.microsandbox/snapshots/<name>/
+// Local: default store. Cloud: managed snapshot storage.
 const snap = await h.snapshot("after-pip-install");
 
 console.log(snap.digest); // sha256:...
@@ -76,7 +90,7 @@ from microsandbox import Sandbox
 
 h = await Sandbox.get("baseline")
 
-# Resolves under ~/.microsandbox/snapshots/<name>/
+# Local: default store. Cloud: managed snapshot storage.
 snap = await h.snapshot("after-pip-install")
 
 print(snap.digest)  # sha256:...
@@ -88,7 +102,7 @@ if err != nil {
     return err
 }
 
-// Resolves under ~/.microsandbox/snapshots/<name>/
+// Local: default store. Cloud: managed snapshot storage.
 snap, err := h.Snapshot(ctx, "after-pip-install")
 
 fmt.Println(snap.Digest()) // sha256:...
@@ -147,7 +161,10 @@ msb run --name worker --from-snapshot after-pip-install -- python -V
 
 </CodeGroup>
 
-Booting validates the snapshot, resolves the pinned image, and gives the new sandbox its own writable copy.
+Booting validates the snapshot, resolves the pinned image, and gives the new
+sandbox its own writable copy. When you already have a `Snapshot` or
+`SnapshotHandle`, pass its stable reference rather than its local path. The
+Python, TypeScript, and Go accept the snapshot object directly.
 
 ## List, inspect, and remove
 
@@ -213,9 +230,13 @@ msb snapshot reindex
 
 </CodeGroup>
 
-`list` and `get` use a local index for fast lookup. If the index gets out of sync, `reindex` rebuilds it from the snapshot artifacts on disk.
+`list` and `get` use the active backend. `reindex`, `list_dir`, `save`, `load`,
+direct artifact-file operations, and full payload verification keep the same
+SDK surface on every backend but currently return a typed `Unsupported` error
+in cloud. Snapshot path references themselves are supported in cloud and are
+resolved relative to the organization's host volume.
 
-## Move snapshots between machines
+## Move local snapshots between machines
 
 The snapshot directory is the whole artifact; there is no hidden daemon state. Copy the directory directly, or save it as an archive:
 

docs/sdk/go/sandbox.mdx

@@ -1031,17 +1031,20 @@ Use a disk image as the root filesystem and optionally provide the inner filesys
 <div className="msb-tags"><span className="msb-tag is-builder">option</span></div>
 
 ```go
-func WithFromSnapshot(pathOrName string) SandboxOption
+func WithFromSnapshot[T SnapshotSeed](snapshot T) SandboxOption
 ```
 
-Boot from a snapshot artifact by bare name or filesystem path. Mutually exclusive with [`WithImage`](#withimage). See [Snapshots](/sdk/go/snapshots).
+Boot from a snapshot using a backend-relative reference. Mutually exclusive
+with [`WithImage`](#withimage). Pass a `SnapshotArtifact` or `SnapshotHandle`
+directly to preserve its typed identifier-or-path reference without inspecting
+the selected backend.
 
 <p className="msb-label">Parameters</p>
 
 <div className="msb-params">
   <div className="msb-param">
-    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
-    <div className="msb-param-desc">Snapshot artifact path or bare name.</div>
+    <div className="msb-param-key"><code>snapshot</code><span className="msb-type">string | *SnapshotArtifact | *SnapshotHandle</span></div>
+    <div className="msb-param-desc">Snapshot object or backend-relative compatibility string.</div>
   </div>
 </div>