> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Create and restore sandbox snapshots with the Go SDK.

<Tooltip tip="Cloud supports disk capture from stopped persistent sandboxes, lookup, listing, removal, and restore. Live capture, full snapshots, groups, archives, verification, and compaction are local-only."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

See the [snapshot guide](/sandboxes/snapshots) for workflows and examples.

Use snapshot objects or references on cloud. Local operations also accept a group head, `group:member`, or artifact path.

## Guest writeback

Set `SnapshotCreateOptions.GuestFlush` to `msb.GuestFlushRequired`, pass `msb.WithForkGuestFlush(msb.GuestFlushRequired)` to `Fork`/`ForkMany`, or call `source.PauseWithGuestFlush(ctx, msb.GuestFlushRequired)`. The default `GuestFlushAuto` flushes live disk-only captures, but adds no optional flush to full captures, forks, or pause. `GuestFlushSkip` retains mandatory storage barriers. A paused disk capture needs a matching prior flush; cloud rejects non-Auto policies. See [guest flush policy reference](/sandboxes/snapshots#guest-flushing).

Disk capture, including `SandboxHandle.Snapshot`, requires a native library that supports guest-flush policies. Older libraries return an upgrade-required error, including for stopped disk captures. Full Auto capture and unrelated operations retain their compatibility.

## 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 disk snapshot, or set `Full` to include memory and execution state. [`SnapshotCreateOptions.FromSandbox`](#snapshotcreateoptionsstruct) is required. An empty `Name` is generated; an empty `Group` uses the source sandbox's name.

<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="#snapshotartifact">\*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:            "deps",
      FromSandbox:     "baseline",
      Labels:          map[string]string{"stage": "post-deps"},
      RecordIntegrity: true,
  })
  ```
</Accordion>

***

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

```go theme={null}
func (snapshotFactory) CreateArchive(ctx context.Context, opts SnapshotArchiveOptions) (*SnapshotArchive, error)
```

Capture directly into an archive without installing a local snapshot.

<Accordion title="Example">
  ```go theme={null}
  archive, err := m.Snapshot.CreateArchive(ctx, m.SnapshotArchiveOptions{
      SnapshotCreateOptions: m.SnapshotCreateOptions{
          Name:        "deps",
          FromSandbox: "baseline",
      },
      ArchivePath: "/tmp/deps.msb",
  })
  ```
</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, "baseline:deps")
  ```
</Accordion>

Open an existing artifact by group head, `group:member`, or filesystem path. This validates metadata only; call [`s.Verify()`](#s-verify) for content checks.

<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">Group head or <code>group:member</code> selector or artifact directory 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="#snapshotartifact">\*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, "baseline:deps")
  ```
</Accordion>

Look up a lightweight handle by group head, `group:member`, stable snapshot ID, descriptor digest, or artifact path. Global IDs and digests must resolve unambiguously.

<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">Group head, <code>group:member</code>, stable snapshot ID, digest, or artifact 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="#snapshothandle">\*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="#snapshothandle">\[]\*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="#snapshotartifact">\[]\*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, "baseline:deps", 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">Group head, <code>group:member</code>, 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 snapshot into a `.msb` archive at `outPath`. Set [`SnapshotSaveOptions.PlainTar`](#snapshotsaveoptionsstruct) to skip compression.

<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">Group head, <code>group:member</code>, 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, "baseline:deps", "/tmp/snap.msb",
      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="#snapshothandle">\*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.msb", "")
  ```
</Accordion>

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

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

Import an archive with an explicit dependency base or destination group. See [import options](#import-options).

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

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

Import an archive with an explicit dependency base or destination group. See [import options](#import-options).

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

```go theme={null}
func (snapshotFactory) LoadMany(
    ctx context.Context, archives []string, opts SnapshotLoadOptions,
) ([]*SnapshotHandle, error)
```

Import archives as one batch. Returns handles in input order. Dependencies resolve from the batch, the named group, or an explicit base; input order does not matter. All members are validated before publication.

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

```go theme={null}
func (snapshotFactory) GroupHead(
    ctx context.Context, selector string,
) (*SnapshotHeadUpdate, error)
```

Read a group’s head, or select an exact member with `group:member`. Returns the group, previous and current snapshot IDs, reason, and whether the head changed. See [group selection](/sandboxes/snapshots#snapshot-groups).

<span id="snapshot-groups" />

<span id="load-multiple-archives" />

### Import options

Options for `SnapshotLoadOptions`.

| Option | Purpose |
| - | - |
| `Dest` | Parent directory containing groups. Defaults to the local snapshot store. |
| `Base` | External snapshot or standalone archive for missing dependencies. |
| `Group` | Destination group. Omit to create one group for the import. |
| `SetHead` | Select the imported tip, even with divergent ancestry. Defaults to false; requires a unique tip. |

With divergent tips, the existing head stays selected; a new group has no head. Select a member explicitly. Identical members may be reused; conflicting identities fail. See [archive imports](/sandboxes/snapshots#import-archives).

## SandboxHandle methods

Snapshots are taken from a metadata handle returned by [`GetSandbox`](/sdk/go/sandbox#m-getsandbox). Local disk capture also supports a running or paused sandbox. Cloud requires a stopped persistent source.

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

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

#### <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 into its default group with the given member name. Local live disk captures preserve the source's running or paused state. Cloud requires a stopped persistent source. Use the returned artifact path or `sandbox:member` to open it later.

<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">Member name within the source sandbox's group.</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="#snapshotartifact">\*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, "deps")
  ```
</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">CopyTo()</span>

```go theme={null}
func (s *SnapshotArtifact) CopyTo(outputArchivePath string) *SnapshotCopyBuilder
```

Create a new archive from this snapshot's disk data while replacing its labels
and integrity metadata. The source snapshot is unchanged. Cloud returns
`ErrUnsupportedOperation` when `Save` is called.

```go theme={null}
err := snap.CopyTo("/tmp/snap-copy.tar.zst").
    Labels(map[string]string{"environment": "test"}).
    RecordIntegrity(true).
    Save(ctx)
```

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

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

Stable opaque `snap_...` identity.

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

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

Verify the snapshot's complete state closure. File state recomputes recorded upper-layer integrity. Checkpoint state validates the complete checkpoint closure and returns its root in `Checkpoint`.

<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 `RestoreSandbox` 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 `SnapshotScopeFull` (`"full"`).

***

#### <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="#snapshotartifact">\*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 installed snapshot copy by its stored artifact path. Other groups containing the same snapshot ID or digest remain unchanged.

<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
```

Member name within its group, or `nil` when no alias is recorded. 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 `SnapshotScopeFull` (`"full"`).

***

#### <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.

<span id="restore-a-sandbox" />

## Restore

Restore into a new detached sandbox. Disk boots fresh; full resumes execution. See [restore examples](/sandboxes/snapshots#disk-snapshots) and [progress](/sandboxes/snapshots#restore-progress).

<Accordion title="Example">
  ```go theme={null}
  child, err := m.RestoreSandbox(ctx, "api:baseline", "api-restored", m.WithCowMemory())
  ```
</Accordion>

| Control | Purpose |
| - | - |
| `WithCowMemory()` | Share unchanged full-snapshot memory. |
| `WithForked() / RestoreConfig.Forked` | Deprecated alias for the same CoW memory policy; see [migration notes](/sandboxes/snapshots#migrating-restore-options). |
| `WithSnapshotDiskOnly()` | Boot only the saved disk. |
| `WithSnapshotBase(base)` | Supply an archive dependency. |
| `RestoreSandbox` | Return the restored sandbox. |
| `RestoreSandboxWithProgress` | Return event and result channels. |

Image, replacement, and startup-command options are not accepted. Full restore requires matching CPU and memory settings, keeps captured network devices, and cannot apply a new guest security profile. Use disk-only restore to change these.

Full restore rejects missing external filesystems and additional disks by default. Use `WithAllowMissingResources()` to resume with unavailable devices and warnings. This is separate from strict/relaxed validation of supplied mappings; inheritance does not waive missing backing. Root and owned storage remain required.

<Accordion title="Destination options">
  | Option | Purpose |
  | - | - |
  | `WithRestoreCPUs, WithRestoreMemory` | CPU count and memory in MiB. Full restore must match capture. |
  | `WithRestoreNetworkPolicy` | Replace host traffic filtering; guest DNS and TLS settings stay unchanged. |
  | `WithRestoreMaxConnections` | Concurrent TCP limit; zero means unlimited. |
  | `WithRestoreDisableNetwork` | Remove the NIC. Rejected for full snapshots that captured one. |
  | `WithRestoreSecurityProfile` | Guest security profile. Disk boot only, including an explicit default profile. |
  | `WithRestoreMaxDuration, WithRestoreIdleTimeout` | Lifetime and idle limits. Omitted means unlimited; zero expires immediately. |
  | `Volumes, CapturedVolumes` | Map host volumes or select captured private volumes. |
  | `Ports` | Bind destination TCP or UDP ports. |
  | `Vsock` | Bind destination vsock endpoints. |
  | `User, LogLevel` | Default user for new execs and host runtime log level. |
  | `WithDangerouslyInheritResources` | Explicitly inherit host resources. Disabled by default. |
  | `WithAllowMissingResources()` | Allow unavailable external filesystems or additional disks, with warnings. Full restore otherwise requires their bindings. |
  | `WithExternalMountPolicy` | Validate supplied filesystem mappings: strict (default) or relaxed. Does not grant access. |

  Omitted controls retain destination defaults. Durations use `time.Duration`, rounded up to seconds. Binding fields belong in `WithRestoreConfig(RestoreConfig{...})`; nil pointers mean omitted. Network policy accepts factory results or `NetworkConfig` with only `Rules`, `DefaultEgress`, and `DefaultIngress`.
</Accordion>

<span id="disk-maintenance-and-incremental-export" />

## Compaction

Compact a local sandbox’s root or owned disks. See [compaction](/sandboxes/snapshots#compact-disks) for examples and recovery requirements.

<Accordion title="Options and results">
  | Option | Purpose |
  | - | - |
  | `Disk` | Select one owned disk by guest path; `/` selects the root. |
  | `RootDiskOnly` | Select only the root. Cannot combine with the disk selector. |
  | `Layers` | Oldest sealed layers to merge, including the base. Minimum two; omit for all. Excludes the writable layer. |
  | `DryRun` | Preview without changing storage. |

  Defaults to the root and owned data disks; excludes named/external volumes and directories. Requires a running or fully stopped local sandbox. Fewer than two sealed layers means no change; no eligible disks returns an empty result with zero counts.

  Results include aggregate counts and per-disk entries keyed by `GuestPath`. `MaterializedBytes` counts copied bytes, not reclaimed space. Times are microseconds: per-disk `TotalUs` covers preparation; aggregate `TotalUs` also includes switching; `PauseUs` measures the shared VM pause.
</Accordion>

## Constants

<p className="msb-member-group">Snapshot scopes</p>

<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: disk-only or disk plus complete VM state.

| Constant | Value | Description |
| - | - | - |
| `SnapshotScopeDisk` | `"disk"` | Disk-only snapshot |
| `SnapshotScopeFull` | `"full"` | Disk plus complete VM execution state |

## Types

<span id="snapshotartifact" />

### 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 snapshot. Fields are unexported; read them through the
accessor methods below.

| Method | Returns | Description |
| - | - | - |
| `ID()` | `string` | Stable opaque snapshot identity |
| `Path()` | `string` | Local artifact directory; panics on cloud |
| `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 `SnapshotScopeFull` |
| [`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 |
| [`CopyTo(outputArchivePath)`](#s-copyto) | `*SnapshotCopyBuilder` | Configure a copied archive with replacement metadata |
| [`Verify(ctx)`](#s-verify) | `(*SnapshotVerifyReport, error)` | Recompute content integrity |

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

Returned by [`SnapshotArtifact.CopyTo`](#s-copyto). Fields are unexported; use
the fluent methods below.

| Method | Returns | Description |
| - | - | - |
| `Labels(map[string]string)` | `*SnapshotCopyBuilder` | Replace all labels in the copied manifest |
| `RecordIntegrity(bool)` | `*SnapshotCopyBuilder` | Compute integrity when true, or omit it when false |
| `Save(context.Context)` | `error` | Write the configured archive |

<span id="snapshothandle" />

### 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 |
| - | - | - |
| `ID()` | `string` | Stable opaque snapshot identity |
| `Path()` | `string` | Local artifact directory; panics on cloud |
| [`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 `SnapshotScopeFull` |
| [`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). `FromSandbox` is required. An empty `Name` is generated; an empty `Group` uses the source sandbox's name.

| Field | Type | Description |
| - | - | - |
| Name | `string` | Member name within its group; generated when empty |
| Group | `string` | Destination snapshot group; defaults to the source sandbox's name |
| FromSandbox | `string` | Name of the source sandbox; local disk capture supports running, paused, stopped, and crashed sources. Cloud requires a stopped persistent source |
| DestDir | `string` | Parent directory containing snapshot groups; empty = the default snapshots directory |
| Labels | `map[string]string` | Arbitrary user labels recorded in the manifest |
| Force | `bool` | Overwrite a direct archive output; rejected for installed group members |
| RecordIntegrity | `bool` | Record content hashes so [`Verify`](#s-verify) can recompute them later |
| Full | `bool` | Local-only when `true`: include memory and execution state from a running or paused source. With `false`, local disk capture supports running, paused, stopped, or crashed sources. Cloud requires `false` and a stopped persistent source |
| GuestFlush | `GuestFlush` | Guest writeback policy; defaults to `GuestFlushAuto`. See [guest writeback](#guest-writeback) |

### 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 |
| - | - | - |
| Since | `string` | Omit disk layers and RAM objects supplied by an exact base; incompatible with `LastLayers` and `WithParents` |
| LastLayers | `*uint32` | Include the newest N sealed root-disk layers; owned disks and full execution state remain complete |
| 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 `.msb` |

### 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 |
| Checkpoint | `*SnapshotCheckpointVerifyStatus` | Verified checkpoint root for full state; otherwise `nil` |

### 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.