> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Go SDK - Snapshot API reference

Disk-only snapshots of a sandbox that is not running. Local snapshots are
portable artifacts; cloud snapshots use managed storage or the organization's
host volume. See [Snapshots](/sandboxes/snapshots) for concepts and walkthroughs.

<Note>
  Snapshots are **disk-only** and require a sandbox that is stopped or crashed.
  `ListDir`, `Reindex`, `Save`/`SaveTo`, `Load`, and `Verify` retain the same
  API on every backend, but currently return `ErrUnsupportedOperation` in cloud.
</Note>

## Snapshot functions

Package-level helpers for snapshot artifacts. Access them through the exported `Snapshot` value, e.g. `m.Snapshot.Create(ctx, ...)`.

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Create()</span>

```go theme={null}
func (snapshotFactory) Create(ctx context.Context, opts SnapshotCreateOptions) (*SnapshotArtifact, error)
```

Create a snapshot from a stopped or crashed sandbox. With no `DestDir`, local
uses its default snapshot directory and cloud uses managed storage. `DestDir`
selects a local parent or cloud host-volume directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#snapshotcreateoptionsstruct">SnapshotCreateOptions</a></div>
    <div className="msb-param-desc">Name, source sandbox, labels, and integrity options.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The created local or cloud snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  snap, err := m.Snapshot.Create(ctx, m.SnapshotCreateOptions{
      Name:            "after-pip-install",
      FromSandbox:     "baseline",
      Labels:          map[string]string{"stage": "post-deps"},
      RecordIntegrity: true,
  })
  ```
</Accordion>

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Open()</span>

```go theme={null}
func (snapshotFactory) Open(ctx context.Context, pathOrName string) (*SnapshotArtifact, error)
```

<Accordion title="Example">
  ```go theme={null}
  snap, err := m.Snapshot.Open(ctx, "after-pip-install")
  ```
</Accordion>

Open an existing snapshot using a backend-relative string. Bare values identify
managed snapshots in cloud; path-like values identify host-volume artifacts.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Backend-relative snapshot name, ID, or path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The opened local or cloud snapshot.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Get()</span>

```go theme={null}
func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)
```

<Accordion title="Example">
  ```go theme={null}
  h, err := m.Snapshot.Get(ctx, "after-pip-install")
  ```
</Accordion>

Look up a lightweight handle through the active backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrDigest</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Public identifier understood by the active backend, such as a local name/digest or cloud snapshot ID.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandlestruct">\*SnapshotHandle</a></div>
    <div className="msb-param-desc">Lightweight handle returned by the active backend.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">List()</span>

```go theme={null}
func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)
```

<Accordion title="Example">
  ```go theme={null}
  handles, err := m.Snapshot.List(ctx)
  for _, h := range handles {
      fmt.Println(h.Digest(), h.ImageRef())
  }
  ```
</Accordion>

List snapshots visible through the active backend. Cloud lists managed
snapshots; host-volume artifacts are opened explicitly by reference.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandlestruct">\[]\*SnapshotHandle</a></div>
    <div className="msb-param-desc">All indexed handles.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">ListDir()</span>

```go theme={null}
func (snapshotFactory) ListDir(ctx context.Context, dir string) ([]*SnapshotArtifact, error)
```

Walk a local directory and parse each subdirectory's manifest without touching
the local index. Cloud returns `ErrUnsupportedOperation`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Directory holding snapshot artifact subdirectories.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">\[]\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">One artifact per parsed subdirectory.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Remove()</span>

```go theme={null}
func (snapshotFactory) Remove(ctx context.Context, pathOrName string, force bool) error
```

<Accordion title="Example">
  ```go theme={null}
  err := m.Snapshot.Remove(ctx, "after-pip-install", false)
  ```
</Accordion>

Remove a snapshot through the active backend. Locally, removal also updates
the index and refuses indexed children unless `force` is true.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name or artifact path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Delete even if the snapshot has indexed children.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Reindex()</span>

```go theme={null}
func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)
```

<Accordion title="Example">
  ```go theme={null}
  n, err := m.Snapshot.Reindex(ctx, "/srv/snapshots")
  fmt.Printf("indexed %d snapshots\n", n)
  ```
</Accordion>

Walk `dir` and rebuild the local index from the artifacts it finds. Cloud
returns `ErrUnsupportedOperation`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Directory to scan for snapshot artifacts.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">uint32</span></div>
    <div className="msb-param-desc">Number of artifacts indexed.</div>
  </div>
</div>

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Save()</span>

<div className="msb-tags"><span className="msb-tag is-static">function</span></div>

```go theme={null}
func (snapshotFactory) Save(ctx context.Context, nameOrPath, outPath string, opts SnapshotSaveOptions) error
```

Bundle a local snapshot into a `.tar.zst` archive at `outPath`. Set
[`SnapshotSaveOptions.PlainTar`](#snapshotsaveoptionsstruct) to skip
compression. Cloud returns `ErrUnsupportedOperation`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name or artifact path to save.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>outPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination archive path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#snapshotsaveoptionsstruct">SnapshotSaveOptions</a></div>
    <div className="msb-param-desc">Whether to include parents, the base image, and compression.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  err := m.Snapshot.Save(ctx, "after-pip-install", "/tmp/snap.tar.zst",
      m.SnapshotSaveOptions{WithParents: true},
  )
  ```
</Accordion>

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">Load()</span>

<div className="msb-tags"><span className="msb-tag is-static">function</span></div>

```go theme={null}
func (snapshotFactory) Load(ctx context.Context, archive, dest string) (*SnapshotHandle, error)
```

Unpack a snapshot archive into the local snapshots directory or an explicit
`dest` directory. Pass `""` for the default destination. Cloud returns
`ErrUnsupportedOperation`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>archive</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path to the snapshot archive.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dest</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination directory, or <code>""</code> for the default snapshots directory.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandlestruct">\*SnapshotHandle</a></div>
    <div className="msb-param-desc">Handle to the loaded snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  h, err := m.Snapshot.Load(ctx, "/tmp/snap.tar.zst", "")
  ```
</Accordion>

## SandboxHandle methods

Snapshots are taken from a metadata handle, so stop the sandbox first and then call [`GetSandbox`](/sdk/go/sandbox#getsandbox).

```go theme={null}
_ = sb.Stop(ctx)
_ = sb.Close()

h, err := m.GetSandbox(ctx, "baseline")
if err != nil {
    return err
}
snap, err := h.Snapshot(ctx, "after-pip-install")
```

#### <span className="msb-recv">h.</span><span className="msb-hn">Snapshot()</span>

```go theme={null}
func (h *SandboxHandle) Snapshot(ctx context.Context, name string) (*SnapshotArtifact, error)
```

Snapshot this sandbox under a bare name. Local uses its default snapshot
directory; cloud uses managed storage. The sandbox must be stopped or crashed.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Bare name for the artifact.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The created artifact.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  snap, err := h.Snapshot(ctx, "after-pip-install")
  ```
</Accordion>

## SnapshotArtifact methods

A local or cloud disk snapshot. The accessors below are plain field reads.

#### <span className="msb-recv">s.</span><span className="msb-hn">SaveTo()</span>

```go theme={null}
func (s *SnapshotArtifact) SaveTo(
    ctx context.Context,
    outPath string,
    opts SnapshotSaveOptions,
) error
```

Bundle this snapshot through the active backend while preserving its typed
identifier-or-path reference. Cloud returns `ErrUnsupportedOperation`.

```go theme={null}
err := snap.SaveTo(ctx, "/tmp/snap.tar.zst", m.SnapshotSaveOptions{
    WithImage: true,
})
```

#### <span className="msb-recv">s.</span><span className="msb-hn">Verify()</span>

```go theme={null}
func (s *SnapshotArtifact) Verify(ctx context.Context) (*SnapshotVerifyReport, error)
```

Recompute the upper layer's recorded content integrity and compare against the descriptor. Current BLAKE3 Merkle integrity skips known all-hole subtrees and hashes allocated leaves in batches; released SHA descriptors retain their exact, potentially O(logical size), verifier. The report's `Upper.Kind` is `"not_recorded"` when the artifact was created without [`RecordIntegrity`](#snapshotcreateoptionsstruct), and `"verified"` when the recorded value matched.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotverifyreportstruct">\*SnapshotVerifyReport</a></div>
    <div className="msb-param-desc">Recomputed digest and upper-layer status.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  report, err := snap.Verify(ctx)
  if err != nil {
      return err
  }
  if report.Upper.Kind == "not_recorded" {
      fmt.Println("snapshot has no recorded payload integrity")
  } else {
      fmt.Println(report.Upper.Digest)
  }
  ```
</Accordion>

#### <span className="msb-recv">s.</span><span className="msb-hn">Reference()</span>

```go theme={null}
func (s *SnapshotArtifact) Reference() string
```

Stable backend-relative value. Prefer passing the `SnapshotArtifact` itself to
`WithFromSnapshot` so its typed reference is preserved as well.

#### <span className="msb-recv">s.</span><span className="msb-hn">ReferenceKind()</span>

```go theme={null}
func (s *SnapshotArtifact) ReferenceKind() string
```

Returns `"id"` or `"path"`. Most callers can pass the artifact itself and
never inspect this value.

#### <span className="msb-recv">s.</span><span className="msb-hn">Digest()</span>

```go theme={null}
func (s *SnapshotArtifact) Digest() string
```

Canonical manifest digest (`sha256:...`).

#### <span className="msb-recv">s.</span><span className="msb-hn">SizeBytes()</span>

```go theme={null}
func (s *SnapshotArtifact) SizeBytes() *uint64
```

Backend-reported stored payload size in bytes.

#### <span className="msb-recv">s.</span><span className="msb-hn">ImageRef()</span>

```go theme={null}
func (s *SnapshotArtifact) ImageRef() string
```

Image reference the snapshot was taken from.

#### <span className="msb-recv">s.</span><span className="msb-hn">ImageManifestDigest()</span>

```go theme={null}
func (s *SnapshotArtifact) ImageManifestDigest() string
```

Pinned OCI manifest digest of the base image.

#### <span className="msb-recv">s.</span><span className="msb-hn">Format()</span>

```go theme={null}
func (s *SnapshotArtifact) Format() string
```

Upper-layer disk format: `"raw"` or `"qcow2"`.

***

#### <span className="msb-recv">s.</span><span className="msb-hn">Scope()</span>

<div className="msb-tags"><span className="msb-tag is-instance">method</span></div>

```go theme={null}
func (s *SnapshotArtifact) Scope() string
```

Snapshot scope: `SnapshotScopeDisk` (`"disk"`) or `SnapshotScopeResumable` (`"resumable"`). Always `SnapshotScopeDisk` today; `SnapshotScopeResumable` is reserved for resumable snapshots.

***

#### <span className="msb-recv">s.</span><span className="msb-hn">Fstype()</span>

```go theme={null}
func (s *SnapshotArtifact) Fstype() string
```

Filesystem type inside the upper layer.

#### <span className="msb-recv">s.</span><span className="msb-hn">Parent()</span>

```go theme={null}
func (s *SnapshotArtifact) Parent() *string
```

Parent digest, or `nil` if this snapshot has no parent. Returns a defensive copy.

#### <span className="msb-recv">s.</span><span className="msb-hn">CreatedAt()</span>

```go theme={null}
func (s *SnapshotArtifact) CreatedAt() string
```

RFC 3339 creation timestamp.

#### <span className="msb-recv">s.</span><span className="msb-hn">Labels()</span>

```go theme={null}
func (s *SnapshotArtifact) Labels() map[string]string
```

User labels recorded at creation. Returns a defensive copy.

#### <span className="msb-recv">s.</span><span className="msb-hn">SourceSandbox()</span>

```go theme={null}
func (s *SnapshotArtifact) SourceSandbox() *string
```

Best-effort source sandbox name, or `nil`. Returns a defensive copy.

## SnapshotHandle methods

A lightweight handle returned by the active backend. The handle retains a
stable reference used by [`Open`](#h-open), [`Remove`](#h-remove), and
[`SaveTo`](#h-saveto).

#### <span className="msb-recv">h.</span><span className="msb-hn">Open()</span>

```go theme={null}
func (h *SnapshotHandle) Open(ctx context.Context) (*SnapshotArtifact, error)
```

<Accordion title="Example">
  ```go theme={null}
  snap, err := h.Open(ctx)
  ```
</Accordion>

Open the underlying snapshot metadata using this handle's stable reference.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The opened artifact.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">Remove()</span>

```go theme={null}
func (h *SnapshotHandle) Remove(ctx context.Context, force bool) error
```

<Accordion title="Example">
  ```go theme={null}
  err := h.Remove(ctx, false)
  ```
</Accordion>

Remove this snapshot using this handle's stable reference.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div>
    <div className="msb-param-desc">Cancellation and deadline.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Delete even if the snapshot has indexed children.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">SaveTo()</span>

```go theme={null}
func (h *SnapshotHandle) SaveTo(
    ctx context.Context,
    outPath string,
    opts SnapshotSaveOptions,
) error
```

Bundle the referenced snapshot through the active backend while preserving the
handle's typed identifier-or-path reference. Cloud returns
`ErrUnsupportedOperation`.

#### <span className="msb-recv">h.</span><span className="msb-hn">Digest()</span>

```go theme={null}
func (h *SnapshotHandle) Digest() string
```

Manifest digest.

#### <span className="msb-recv">h.</span><span className="msb-hn">Name()</span>

```go theme={null}
func (h *SnapshotHandle) Name() *string
```

Bare-name alias, if the snapshot was indexed with one; otherwise `nil`. Returns a defensive copy.

#### <span className="msb-recv">h.</span><span className="msb-hn">ParentDigest()</span>

```go theme={null}
func (h *SnapshotHandle) ParentDigest() *string
```

Parent digest, or `nil`. Returns a defensive copy.

#### <span className="msb-recv">h.</span><span className="msb-hn">ImageRef()</span>

```go theme={null}
func (h *SnapshotHandle) ImageRef() string
```

Pinned image reference.

#### <span className="msb-recv">h.</span><span className="msb-hn">Format()</span>

```go theme={null}
func (h *SnapshotHandle) Format() string
```

Upper-layer disk format: `"raw"` or `"qcow2"`.

***

#### <span className="msb-recv">h.</span><span className="msb-hn">Scope()</span>

<div className="msb-tags"><span className="msb-tag is-instance">method</span></div>

```go theme={null}
func (h *SnapshotHandle) Scope() string
```

Snapshot scope: `SnapshotScopeDisk` (`"disk"`) or `SnapshotScopeResumable` (`"resumable"`). Always `SnapshotScopeDisk` today.

***

#### <span className="msb-recv">h.</span><span className="msb-hn">SizeBytes()</span>

```go theme={null}
func (h *SnapshotHandle) SizeBytes() *uint64
```

Backend-reported stored payload size, or `nil` if unknown.

#### <span className="msb-recv">h.</span><span className="msb-hn">ReferenceKind()</span>

```go theme={null}
func (h *SnapshotHandle) ReferenceKind() string
```

Returns `"id"` or `"path"` for the handle's backend-neutral reference.

#### <span className="msb-recv">h.</span><span className="msb-hn">CreatedAt()</span>

```go theme={null}
func (h *SnapshotHandle) CreatedAt() time.Time
```

Snapshot creation time, decoded from the index's Unix timestamp.

## Types

### SnapshotArtifact<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Returned by <a href="#snapshot-create">Snapshot.Create()</a> · <a href="#snapshot-open">Snapshot.Open()</a> · <a href="#snapshot-listdir">Snapshot.ListDir()</a> · <a href="#h-snapshot">h.Snapshot()</a> · <a href="#h-open">h.Open()</a></p>

A backend-neutral disk snapshot. Fields are unexported; read them through the
accessor methods below.

| Method                                            | Returns                          | Description                                      |
| ------------------------------------------------- | -------------------------------- | ------------------------------------------------ |
| `Reference()`                                     | `string`                         | Stable backend-relative restore reference        |
| `ReferenceKind()`                                 | `string`                         | `id` or `path`                                   |
| [`Digest()`](#s-digest)                           | `string`                         | Canonical manifest digest (`sha256:...`)         |
| [`SizeBytes()`](#s-sizebytes)                     | `*uint64`                        | Backend-reported stored payload size, when known |
| [`ImageRef()`](#s-imageref)                       | `string`                         | Image reference the snapshot was taken from      |
| [`ImageManifestDigest()`](#s-imagemanifestdigest) | `string`                         | Pinned OCI manifest digest                       |
| [`Format()`](#s-format)                           | `string`                         | `"raw"` or `"qcow2"`                             |
| [`Scope()`](#s-scope)                             | `string`                         | `SnapshotScopeDisk` or `SnapshotScopeResumable`  |
| [`Fstype()`](#s-fstype)                           | `string`                         | Filesystem type inside the upper layer           |
| [`Parent()`](#s-parent)                           | `*string`                        | Parent digest, or nil                            |
| [`CreatedAt()`](#s-createdat)                     | `string`                         | RFC 3339 timestamp                               |
| [`Labels()`](#s-labels)                           | `map[string]string`              | User labels                                      |
| [`SourceSandbox()`](#s-sourcesandbox)             | `*string`                        | Best-effort source sandbox name                  |
| [`SaveTo(ctx, outPath, opts)`](#s-saveto)         | `error`                          | Bundle using this snapshot's typed reference     |
| [`Verify(ctx)`](#s-verify)                        | `(*SnapshotVerifyReport, error)` | Recompute content integrity                      |

### SnapshotHandle<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Returned by <a href="#snapshot-get">Snapshot.Get()</a> · <a href="#snapshot-list">Snapshot.List()</a> · <a href="#snapshot-load">Snapshot.Load()</a></p>

A lightweight handle returned by the active backend. Fields are unexported;
read them through the accessor methods below.

| Method                                    | Returns                      | Description                                     |
| ----------------------------------------- | ---------------------------- | ----------------------------------------------- |
| [`Digest()`](#h-digest)                   | `string`                     | Manifest digest                                 |
| [`Name()`](#h-name)                       | `*string`                    | Bare-name alias, if indexed with one            |
| [`ParentDigest()`](#h-parentdigest)       | `*string`                    | Parent digest, or nil                           |
| [`ImageRef()`](#h-imageref)               | `string`                     | Pinned image reference                          |
| [`Format()`](#h-format)                   | `string`                     | `"raw"` or `"qcow2"`                            |
| [`Scope()`](#h-scope)                     | `string`                     | `SnapshotScopeDisk` or `SnapshotScopeResumable` |
| [`SizeBytes()`](#h-sizebytes)             | `*uint64`                    | Backend-reported stored payload size            |
| `Reference()`                             | `string`                     | Stable backend-relative restore reference       |
| `ReferenceKind()`                         | `string`                     | `id` or `path`                                  |
| [`CreatedAt()`](#h-createdat)             | `time.Time`                  | Snapshot creation time                          |
| [`Open(ctx)`](#h-open)                    | `(*SnapshotArtifact, error)` | Open the artifact metadata                      |
| [`Remove(ctx, force)`](#h-remove)         | `error`                      | Remove this snapshot                            |
| [`SaveTo(ctx, outPath, opts)`](#h-saveto) | `error`                      | Bundle using this handle's typed reference      |

### SnapshotCreateOptions<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Accepted by <a href="#snapshot-create">Snapshot.Create()</a></p>

Configures [`Snapshot.Create`](#snapshot-create). `Name` and `FromSandbox` are both required.

| Field           | Type                | Description                                                                  |
| --------------- | ------------------- | ---------------------------------------------------------------------------- |
| Name            | `string`            | Snapshot name; storage location is selected by the active backend            |
| FromSandbox     | `string`            | Name of the stopped or crashed sandbox to capture                            |
| DestDir         | `string`            | Local parent or cloud host-volume directory; empty = backend-managed storage |
| Labels          | `map[string]string` | Arbitrary user labels recorded in the manifest                               |
| Force           | `bool`              | Overwrite an existing artifact with the same name                            |
| RecordIntegrity | `bool`              | Record content hashes so [`Verify`](#s-verify) can recompute them later      |
| Resumable       | `bool`              | Request a resumable snapshot; returns an unsupported-feature error today     |

### SnapshotSaveOptions<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Accepted by <a href="#snapshot-save">Snapshot.Save()</a> and instance <code>SaveTo()</code> methods</p>

Configures [`Snapshot.Save`](#snapshot-save) and instance `SaveTo()` methods.

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| WithParents | `bool` | Include the snapshot's parent chain in the archive |
| WithImage   | `bool` | Include the base OCI image in the archive          |
| PlainTar    | `bool` | Write an uncompressed `.tar` instead of `.tar.zst` |

### SnapshotVerifyReport<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Returned by <a href="#s-verify">s.Verify()</a></p>

Result of [`Verify`](#s-verify).

| Field  | Type                                                            | Description                          |
| ------ | --------------------------------------------------------------- | ------------------------------------ |
| Digest | `string`                                                        | Recomputed manifest digest           |
| Path   | `string`                                                        | Artifact directory that was verified |
| Upper  | [`SnapshotUpperVerifyStatus`](#snapshotupperverifystatusstruct) | Upper-layer integrity status         |

### SnapshotUpperVerifyStatus<span className="msb-tag is-type" style={{marginLeft: "8px"}}>struct</span>

<p className="msb-backref">Field of <a href="#snapshotverifyreportstruct">SnapshotVerifyReport</a></p>

Upper-layer integrity details inside a [`SnapshotVerifyReport`](#snapshotverifyreportstruct).

| Field     | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| Kind      | `string` | Integrity record kind         |
| Algorithm | `string` | Hash algorithm used           |
| Digest    | `string` | Recomputed upper-layer digest |

### Snapshot scope constants

<p className="msb-backref">Returned by <a href="#s-scope">s.Scope()</a> · <a href="#h-scope">h.Scope()</a></p>

Scope of what a snapshot captures. Every snapshot today is disk-only; the resumable scope (disk plus VM state) is reserved for resumable snapshots.

| Constant                 | Value         | Description                            |
| ------------------------ | ------------- | -------------------------------------- |
| `SnapshotScopeDisk`      | `"disk"`      | Disk-only snapshot                     |
| `SnapshotScopeResumable` | `"resumable"` | Disk plus VM state (not yet supported) |