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

> Go SDK - Snapshot API reference

Disk-only snapshots of a sandbox that is not running. Create artifacts from a stopped sandbox, list and verify them, export to an archive, and import elsewhere. See [Snapshots](/sandboxes/snapshots) for concepts and walkthroughs; this page is the Go SDK reference.

<Note>
  Snapshots are **disk-only** and require a sandbox that is stopped or crashed.
</Note>

<p className="msb-label" id="typical-flow">Typical flow</p>

```go theme={null}
import m "github.com/superradcompany/microsandbox/sdk/go"

// 1. stop the sandbox; snapshots are disk-only
_ = sb.Stop(ctx)
_ = sb.Close()

// 2. snapshot it under a bare name
snap, err := m.Snapshot.Create(ctx, "baseline", m.SnapshotCreateOptions{
    Name:            "after-pip-install",
    RecordIntegrity: true,
})
if err != nil {
    return err
}

// 3. boot a fresh sandbox from the snapshot
sb2, err := m.CreateSandbox(ctx, "worker",
    m.WithSnapshot("after-pip-install"),
)
```

## 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, sourceSandbox string, opts SnapshotCreateOptions) (*SnapshotArtifact, error)
```

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

Create a snapshot from a stopped or crashed sandbox. Set exactly one of [`SnapshotCreateOptions.Name`](#snapshotcreateoptionsstruct) (resolved under the default snapshots directory) or [`SnapshotCreateOptions.Path`](#snapshotcreateoptionsstruct) (an explicit artifact 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>sourceSandbox</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name of the stopped or crashed sandbox to snapshot.</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">Destination, 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 artifact on disk.</div>
  </div>
</div>

#### <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 artifact by bare name 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">Bare name (resolved under the default snapshots directory) 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="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The artifact on disk.</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 in the local index by name, digest, or path.

<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">Bare name, manifest 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="#snapshothandlestruct">\*SnapshotHandle</a></div>
    <div className="msb-param-desc">Index-backed handle.</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 indexed snapshots from the local DB cache.

<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 directory and parse each subdirectory's manifest without touching the index.

<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 artifact and its index row. Refuses to delete a snapshot with 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.

<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">Export()</span>

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

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

Bundle a snapshot into a `.tar.zst` archive at `outPath`. Set [`SnapshotExportOptions.PlainTar`](#snapshotexportoptionsstruct) 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">Bare name or artifact path to export.</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="#snapshotexportoptionsstruct">SnapshotExportOptions</a></div>
    <div className="msb-param-desc">Whether to include parents, the base image, and compression.</div>
  </div>
</div>

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

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

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

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

<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 imported snapshot.</div>
  </div>
</div>

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

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

Snapshot this sandbox under a bare name in the default snapshots directory. 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>

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

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

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

Snapshot this sandbox to an explicit artifact directory. 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>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination artifact 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="#snapshotartifactstruct">\*SnapshotArtifact</a></div>
    <div className="msb-param-desc">The created artifact.</div>
  </div>
</div>

## SnapshotArtifact methods

An artifact on disk. The accessors below are plain field reads; only [`Verify`](#s-verify) touches the filesystem.

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

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

<Accordion title="Example">
  ```go theme={null}
  report, err := snap.Verify(ctx)
  if err != nil {
      return err
  }
  fmt.Println(report.Upper.Digest)
  ```
</Accordion>

Recompute recorded content integrity for this snapshot. Requires that the artifact was created with [`RecordIntegrity`](#snapshotcreateoptionsstruct) set.

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

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

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

Artifact directory on disk.

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

Apparent upper-layer 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">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 backed by the local index. The accessors below are plain field reads; [`Open`](#h-open) and [`Remove`](#h-remove) take a context.

#### <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 artifact metadata. Equivalent to [`Snapshot.Open`](#snapshot-open) on this handle's path.

<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. Equivalent to [`Snapshot.Remove`](#snapshot-remove) on this handle's digest.

<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">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">SizeBytes()</span>

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

Apparent upper size at index time, or `nil` if unknown. Returns a defensive copy.

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

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

Artifact directory on disk.

#### <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-snapshotto">h.SnapshotTo()</a> · <a href="#h-open">h.Open()</a></p>

A snapshot artifact on disk. Fields are unexported; read them through the accessor methods below.

| Method                                            | Returns                          | Description                                 |
| ------------------------------------------------- | -------------------------------- | ------------------------------------------- |
| [`Path()`](#s-path)                               | `string`                         | Artifact directory                          |
| [`Digest()`](#s-digest)                           | `string`                         | Canonical manifest digest (`sha256:...`)    |
| [`SizeBytes()`](#s-sizebytes)                     | `uint64`                         | Apparent upper-layer size                   |
| [`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"`                        |
| [`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             |
| [`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-import">Snapshot.Import()</a></p>

A lightweight handle backed by the local snapshot index. 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"`                 |
| [`SizeBytes()`](#h-sizebytes)       | `*uint64`                    | Apparent upper size at index time    |
| [`Path()`](#h-path)                 | `string`                     | Artifact directory                   |
| [`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                 |

### 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). Set exactly one of `Name` or `Path`.

| Field           | Type                | Description                                                              |
| --------------- | ------------------- | ------------------------------------------------------------------------ |
| Name            | `string`            | Bare name; the artifact is written under the default snapshots directory |
| Path            | `string`            | Explicit artifact directory (mutually exclusive with `Name`)             |
| Labels          | `map[string]string` | Arbitrary user labels recorded in the manifest                           |
| Force           | `bool`              | Overwrite an existing artifact at the destination                        |
| RecordIntegrity | `bool`              | Record content hashes so [`Verify`](#s-verify) can recompute them later  |

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

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

Configures [`Snapshot.Export`](#snapshot-export).

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