---
title: Snapshots
description: 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.
Snapshots are **disk-only** and require a sandbox that is stopped or crashed.
Typical flow
```go
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, ...)`.
---
#### Snapshot.Create()
function
```go
func (snapshotFactory) Create(ctx context.Context, sourceSandbox string, opts SnapshotCreateOptions) (*SnapshotArtifact, error)
```
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).
Parameters
ctxcontext.Context
Cancellation and deadline.
sourceSandboxstring
Name of the stopped or crashed sandbox to snapshot.
Destination, labels, and integrity options.
Returns
The created artifact on disk.
```go
snap, err := m.Snapshot.Create(ctx, "baseline", m.SnapshotCreateOptions{
Name: "after-pip-install",
Labels: map[string]string{"stage": "post-deps"},
RecordIntegrity: true,
})
```
---
#### Snapshot.Open()
function
```go
func (snapshotFactory) Open(ctx context.Context, pathOrName string) (*SnapshotArtifact, error)
```
Open an existing artifact by bare name or filesystem path. This validates metadata only; call [`s.Verify()`](#s-verify) for content checks.
Parameters
ctxcontext.Context
Cancellation and deadline.
pathOrNamestring
Bare name (resolved under the default snapshots directory) or artifact directory path.
Returns
```go
snap, err := m.Snapshot.Open(ctx, "after-pip-install")
```
---
#### Snapshot.Get()
function
```go
func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)
```
Look up a lightweight handle in the local index by name, digest, or path.
Parameters
ctxcontext.Context
Cancellation and deadline.
nameOrDigeststring
Bare name, manifest digest, or artifact path.
Returns
```go
h, err := m.Snapshot.Get(ctx, "after-pip-install")
```
---
#### Snapshot.List()
function
```go
func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)
```
List indexed snapshots from the local DB cache.
Returns
```go
handles, err := m.Snapshot.List(ctx)
for _, h := range handles {
fmt.Println(h.Digest(), h.ImageRef())
}
```
---
#### Snapshot.ListDir()
function
```go
func (snapshotFactory) ListDir(ctx context.Context, dir string) ([]*SnapshotArtifact, error)
```
Walk a directory and parse each subdirectory's manifest without touching the index.
Parameters
ctxcontext.Context
Cancellation and deadline.
dirstring
Directory holding snapshot artifact subdirectories.
Returns
One artifact per parsed subdirectory.
---
#### Snapshot.Remove()
function
```go
func (snapshotFactory) Remove(ctx context.Context, pathOrName string, force bool) error
```
Remove a snapshot artifact and its index row. Refuses to delete a snapshot with indexed children unless `force` is true.
Parameters
ctxcontext.Context
Cancellation and deadline.
pathOrNamestring
Bare name or artifact path.
forcebool
Delete even if the snapshot has indexed children.
```go
err := m.Snapshot.Remove(ctx, "after-pip-install", false)
```
---
#### Snapshot.Reindex()
function
```go
func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)
```
Walk `dir` and rebuild the local index from the artifacts it finds.
Parameters
ctxcontext.Context
Cancellation and deadline.
dirstring
Directory to scan for snapshot artifacts.
Returns
uint32
Number of artifacts indexed.
```go
n, err := m.Snapshot.Reindex(ctx, "/srv/snapshots")
fmt.Printf("indexed %d snapshots\n", n)
```
---
#### Snapshot.Export()
function
```go
func (snapshotFactory) Export(ctx context.Context, nameOrPath, outPath string, opts SnapshotExportOptions) error
```
Bundle a snapshot into a `.tar.zst` archive at `outPath`. Set [`SnapshotExportOptions.PlainTar`](#snapshotexportoptionsstruct) to skip compression.
Parameters
ctxcontext.Context
Cancellation and deadline.
nameOrPathstring
Bare name or artifact path to export.
outPathstring
Destination archive path.
Whether to include parents, the base image, and compression.
```go
err := m.Snapshot.Export(ctx, "after-pip-install", "/tmp/snap.tar.zst",
m.SnapshotExportOptions{WithParents: true},
)
```
---
#### Snapshot.Import()
function
```go
func (snapshotFactory) Import(ctx context.Context, archive, dest string) (*SnapshotHandle, error)
```
Unpack a snapshot archive into the snapshots directory or an explicit `dest` directory. Pass `""` for the default destination.
Parameters
ctxcontext.Context
Cancellation and deadline.
archivestring
Path to the snapshot archive.
deststring
Destination directory, or "" for the default snapshots directory.
Returns
Handle to the imported snapshot.
```go
h, err := m.Snapshot.Import(ctx, "/tmp/snap.tar.zst", "")
```
## SandboxHandle methods
Snapshots are taken from a metadata handle, so stop the sandbox first and then call [`GetSandbox`](/sdk/go/sandbox#getsandbox).
```go
_ = sb.Stop(ctx)
_ = sb.Close()
h, err := m.GetSandbox(ctx, "baseline")
if err != nil {
return err
}
snap, err := h.Snapshot(ctx, "after-pip-install")
```
---
#### h.Snapshot()
method
```go
func (h *SandboxHandle) Snapshot(ctx context.Context, name string) (*SnapshotArtifact, error)
```
Snapshot this sandbox under a bare name in the default snapshots directory. The sandbox must be stopped or crashed.
Parameters
ctxcontext.Context
Cancellation and deadline.
namestring
Bare name for the artifact.
Returns
```go
snap, err := h.Snapshot(ctx, "after-pip-install")
```
---
#### h.SnapshotTo()
method
```go
func (h *SandboxHandle) SnapshotTo(ctx context.Context, path string) (*SnapshotArtifact, error)
```
Snapshot this sandbox to an explicit artifact directory. The sandbox must be stopped or crashed.
Parameters
ctxcontext.Context
Cancellation and deadline.
pathstring
Destination artifact directory.
Returns
```go
snap, err := h.SnapshotTo(ctx, "/srv/snapshots/baseline")
```
## SnapshotArtifact methods
An artifact on disk. The accessors below are plain field reads; only [`Verify`](#s-verify) touches the filesystem.
---
#### s.Verify()
method
```go
func (s *SnapshotArtifact) Verify(ctx context.Context) (*SnapshotVerifyReport, error)
```
Recompute recorded content integrity for this snapshot. Requires that the artifact was created with [`RecordIntegrity`](#snapshotcreateoptionsstruct) set.
Returns
Recomputed digest and upper-layer status.
```go
report, err := snap.Verify(ctx)
if err != nil {
return err
}
fmt.Println(report.Upper.Digest)
```
---
#### s.Path()
method
```go
func (s *SnapshotArtifact) Path() string
```
Artifact directory on disk.
---
#### s.Digest()
method
```go
func (s *SnapshotArtifact) Digest() string
```
Canonical manifest digest (`sha256:...`).
---
#### s.SizeBytes()
method
```go
func (s *SnapshotArtifact) SizeBytes() uint64
```
Apparent upper-layer size in bytes.
---
#### s.ImageRef()
method
```go
func (s *SnapshotArtifact) ImageRef() string
```
Image reference the snapshot was taken from.
---
#### s.ImageManifestDigest()
method
```go
func (s *SnapshotArtifact) ImageManifestDigest() string
```
Pinned OCI manifest digest of the base image.
---
#### s.Format()
method
```go
func (s *SnapshotArtifact) Format() string
```
Upper-layer disk format: `"raw"` or `"qcow2"`.
---
#### s.Fstype()
method
```go
func (s *SnapshotArtifact) Fstype() string
```
Filesystem type inside the upper layer.
---
#### s.Parent()
method
```go
func (s *SnapshotArtifact) Parent() *string
```
Parent digest, or `nil` if this snapshot has no parent. Returns a defensive copy.
---
#### s.CreatedAt()
method
```go
func (s *SnapshotArtifact) CreatedAt() string
```
RFC 3339 creation timestamp.
---
#### s.Labels()
method
```go
func (s *SnapshotArtifact) Labels() map[string]string
```
User labels recorded at creation. Returns a defensive copy.
---
#### s.SourceSandbox()
method
```go
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.
---
#### h.Open()
method
```go
func (h *SnapshotHandle) Open(ctx context.Context) (*SnapshotArtifact, error)
```
Open the underlying artifact metadata. Equivalent to [`Snapshot.Open`](#snapshot-open) on this handle's path.
Returns
```go
snap, err := h.Open(ctx)
```
---
#### h.Remove()
method
```go
func (h *SnapshotHandle) Remove(ctx context.Context, force bool) error
```
Remove this snapshot. Equivalent to [`Snapshot.Remove`](#snapshot-remove) on this handle's digest.
Parameters
ctxcontext.Context
Cancellation and deadline.
forcebool
Delete even if the snapshot has indexed children.
```go
err := h.Remove(ctx, false)
```
---
#### h.Digest()
method
```go
func (h *SnapshotHandle) Digest() string
```
Manifest digest.
---
#### h.Name()
method
```go
func (h *SnapshotHandle) Name() *string
```
Bare-name alias, if the snapshot was indexed with one; otherwise `nil`. Returns a defensive copy.
---
#### h.ParentDigest()
method
```go
func (h *SnapshotHandle) ParentDigest() *string
```
Parent digest, or `nil`. Returns a defensive copy.
---
#### h.ImageRef()
method
```go
func (h *SnapshotHandle) ImageRef() string
```
Pinned image reference.
---
#### h.Format()
method
```go
func (h *SnapshotHandle) Format() string
```
Upper-layer disk format: `"raw"` or `"qcow2"`.
---
#### h.SizeBytes()
method
```go
func (h *SnapshotHandle) SizeBytes() *uint64
```
Apparent upper size at index time, or `nil` if unknown. Returns a defensive copy.
---
#### h.Path()
method
```go
func (h *SnapshotHandle) Path() string
```
Artifact directory on disk.
---
#### h.CreatedAt()
method
```go
func (h *SnapshotHandle) CreatedAt() time.Time
```
Snapshot creation time, decoded from the index's Unix timestamp.
## Types
### SnapshotArtifactstruct
Returned by Snapshot.Create() · Snapshot.Open() · Snapshot.ListDir() · h.Snapshot() · h.SnapshotTo() · h.Open()
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 |
### SnapshotHandlestruct
Returned by Snapshot.Get() · Snapshot.List() · Snapshot.Import()
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 |
### SnapshotCreateOptionsstruct
Accepted by Snapshot.Create()
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 |
### SnapshotExportOptionsstruct
Accepted by Snapshot.Export()
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` |
### SnapshotVerifyReportstruct
Returned by s.Verify()
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 |
### SnapshotUpperVerifyStatusstruct
Field of SnapshotVerifyReport
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 |