Snapshots - microsandbox

Disk-only snapshots of a sandbox that is not running. Create artifacts from a stopped sandbox, list and verify them, save to an archive, and load elsewhere. See 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.

Snapshot functions

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

Snapshot.Create()

func (snapshotFactory) Create(ctx context.Context, opts SnapshotCreateOptions) (*SnapshotArtifact, error)

Create a snapshot from a stopped or crashed sandbox. SnapshotCreateOptions.Name (resolved under the default snapshots directory) and SnapshotCreateOptions.FromSandbox (the sandbox to capture) are both required.

Parameters

ctxcontext.Context

Cancellation and deadline.

optsSnapshotCreateOptions

Name, source sandbox, labels, and integrity options.

Returns

*SnapshotArtifact

The created artifact on disk.

Example

snap, err := m.Snapshot.Create(ctx, m.SnapshotCreateOptions{
    Name:            "after-pip-install",
    FromSandbox:     "baseline",
    Labels:          map[string]string{"stage": "post-deps"},
    RecordIntegrity: true,
})

Snapshot.Open()

func (snapshotFactory) Open(ctx context.Context, pathOrName string) (*SnapshotArtifact, error)

Example

snap, err := m.Snapshot.Open(ctx, "after-pip-install")

Open an existing artifact by bare name or filesystem path. This validates metadata only; call 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

*SnapshotArtifact

The artifact on disk.

Snapshot.Get()

func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)

Example

h, err := m.Snapshot.Get(ctx, "after-pip-install")

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

*SnapshotHandle

Index-backed handle.

Snapshot.List()

func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)

Example

handles, err := m.Snapshot.List(ctx)
for _, h := range handles {
    fmt.Println(h.Digest(), h.ImageRef())
}

List indexed snapshots from the local DB cache.

Returns

[]*SnapshotHandle

All indexed handles.

Snapshot.ListDir()

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

[]*SnapshotArtifact

One artifact per parsed subdirectory.

Snapshot.Remove()

func (snapshotFactory) Remove(ctx context.Context, pathOrName string, force bool) error

Example

err := m.Snapshot.Remove(ctx, "after-pip-install", false)

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.

Snapshot.Reindex()

func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)

Example

n, err := m.Snapshot.Reindex(ctx, "/srv/snapshots")
fmt.Printf("indexed %d snapshots\n", n)

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.

Snapshot.Save()

function

func (snapshotFactory) Save(ctx context.Context, nameOrPath, outPath string, opts SnapshotSaveOptions) error

Bundle a snapshot into a .tar.zst archive at outPath. Set SnapshotSaveOptions.PlainTar to skip compression.

Parameters

ctxcontext.Context

Cancellation and deadline.

nameOrPathstring

Bare name or artifact path to save.

outPathstring

Destination archive path.

optsSnapshotSaveOptions

Whether to include parents, the base image, and compression.

Example

err := m.Snapshot.Save(ctx, "after-pip-install", "/tmp/snap.tar.zst",
    m.SnapshotSaveOptions{WithParents: true},
)

Snapshot.Load()

function

func (snapshotFactory) Load(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

*SnapshotHandle

Handle to the loaded snapshot.

Example

h, err := m.Snapshot.Load(ctx, "/tmp/snap.tar.zst", "")

SandboxHandle methods

Snapshots are taken from a metadata handle, so stop the sandbox first and then call GetSandbox.

_ = 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()

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. To place the artifact elsewhere, use Snapshot.Save / Snapshot.Load or move the self-contained artifact directory.

Parameters

ctxcontext.Context

Cancellation and deadline.

namestring

Bare name for the artifact.

Returns

*SnapshotArtifact

The created artifact.

Example

snap, err := h.Snapshot(ctx, "after-pip-install")

SnapshotArtifact methods

An artifact on disk. The accessors below are plain field reads; only Verify touches the filesystem.

s.Verify()

func (s *SnapshotArtifact) Verify(ctx context.Context) (*SnapshotVerifyReport, error)

Recompute the upper layer’s content hash and compare against the manifest. Walks data extents only, so a 4 GiB sparse file with a few MB of data verifies in milliseconds. The report’s Upper.Kind is "not_recorded" when the artifact was created without RecordIntegrity, and "verified" when the recorded hash matched.

Returns

*SnapshotVerifyReport

Recomputed digest and upper-layer status.

Example

report, err := snap.Verify(ctx)
if err != nil {
    return err
}
fmt.Println(report.Upper.Digest)

s.Path()

func (s *SnapshotArtifact) Path() string

Artifact directory on disk.

s.Digest()

func (s *SnapshotArtifact) Digest() string

Canonical manifest digest (sha256:...).

s.SizeBytes()

func (s *SnapshotArtifact) SizeBytes() uint64

Apparent upper-layer size in bytes.

s.ImageRef()

func (s *SnapshotArtifact) ImageRef() string

Image reference the snapshot was taken from.

s.ImageManifestDigest()

func (s *SnapshotArtifact) ImageManifestDigest() string

Pinned OCI manifest digest of the base image.

s.Format()

func (s *SnapshotArtifact) Format() string

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

s.Scope()

method

func (s *SnapshotArtifact) Scope() string

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

s.Fstype()

func (s *SnapshotArtifact) Fstype() string

Filesystem type inside the upper layer.

s.Parent()

func (s *SnapshotArtifact) Parent() *string

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

s.CreatedAt()

func (s *SnapshotArtifact) CreatedAt() string

RFC 3339 creation timestamp.

s.Labels()

func (s *SnapshotArtifact) Labels() map[string]string

User labels recorded at creation. Returns a defensive copy.

s.SourceSandbox()

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 and Remove take a context.

h.Open()

func (h *SnapshotHandle) Open(ctx context.Context) (*SnapshotArtifact, error)

Example

snap, err := h.Open(ctx)

Open the underlying artifact metadata. Equivalent to Snapshot.Open on this handle’s path.

Returns

*SnapshotArtifact

The opened artifact.

h.Remove()

func (h *SnapshotHandle) Remove(ctx context.Context, force bool) error

Example

err := h.Remove(ctx, false)

Remove this snapshot. Equivalent to Snapshot.Remove on this handle’s digest.

Parameters

ctxcontext.Context

Cancellation and deadline.

forcebool

Delete even if the snapshot has indexed children.

h.Digest()

func (h *SnapshotHandle) Digest() string

Manifest digest.

h.Name()

func (h *SnapshotHandle) Name() *string

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

h.ParentDigest()

func (h *SnapshotHandle) ParentDigest() *string

Parent digest, or nil. Returns a defensive copy.

h.ImageRef()

func (h *SnapshotHandle) ImageRef() string

Pinned image reference.

h.Format()

func (h *SnapshotHandle) Format() string

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

h.Scope()

method

func (h *SnapshotHandle) Scope() string

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

h.SizeBytes()

func (h *SnapshotHandle) SizeBytes() *uint64

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

h.Path()

func (h *SnapshotHandle) Path() string

Artifact directory on disk.

h.CreatedAt()

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.Open()

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

Method	Returns	Description
`Path()`	`string`	Artifact directory
`Digest()`	`string`	Canonical manifest digest (`sha256:...`)
`SizeBytes()`	`uint64`	Apparent upper-layer size
`ImageRef()`	`string`	Image reference the snapshot was taken from
`ImageManifestDigest()`	`string`	Pinned OCI manifest digest
`Format()`	`string`	`"raw"` or `"qcow2"`
`Scope()`	`string`	`SnapshotScopeDisk` or `SnapshotScopeResumable`
`Fstype()`	`string`	Filesystem type inside the upper layer
`Parent()`	`*string`	Parent digest, or nil
`CreatedAt()`	`string`	RFC 3339 timestamp
`Labels()`	`map[string]string`	User labels
`SourceSandbox()`	`*string`	Best-effort source sandbox name
`Verify(ctx)`	`(*SnapshotVerifyReport, error)`	Recompute content integrity

SnapshotHandlestruct

Returned by Snapshot.Get() · Snapshot.List() · Snapshot.Load()

A lightweight handle backed by the local snapshot index. Fields are unexported; read them through the accessor methods below.

Method	Returns	Description
`Digest()`	`string`	Manifest digest
`Name()`	`*string`	Bare-name alias, if indexed with one
`ParentDigest()`	`*string`	Parent digest, or nil
`ImageRef()`	`string`	Pinned image reference
`Format()`	`string`	`"raw"` or `"qcow2"`
`Scope()`	`string`	`SnapshotScopeDisk` or `SnapshotScopeResumable`
`SizeBytes()`	`*uint64`	Apparent upper size at index time
`Path()`	`string`	Artifact directory
`CreatedAt()`	`time.Time`	Snapshot creation time
`Open(ctx)`	`(*SnapshotArtifact, error)`	Open the artifact metadata
`Remove(ctx, force)`	`error`	Remove this snapshot

SnapshotCreateOptionsstruct

Accepted by Snapshot.Create()

Configures Snapshot.Create. Name and FromSandbox are both required.

Field	Type	Description
Name	`string`	Bare name; always the artifact directory’s basename
FromSandbox	`string`	Name of the stopped or crashed sandbox to capture
DestDir	`string`	Parent directory for the artifact (`DestDir/<name>`); empty = the default snapshots directory
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` can recompute them later
Resumable	`bool`	Request a resumable snapshot; returns an unsupported-feature error today

SnapshotSaveOptionsstruct

Accepted by Snapshot.Save()

Configures Snapshot.Save.

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.

Field	Type	Description
Digest	`string`	Recomputed manifest digest
Path	`string`	Artifact directory that was verified
Upper	`SnapshotUpperVerifyStatus`	Upper-layer integrity status

SnapshotUpperVerifyStatusstruct

Field of SnapshotVerifyReport

Upper-layer integrity details inside a SnapshotVerifyReport.

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

Snapshot scope constants

Returned by s.Scope() · h.Scope()

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)

​Snapshot functions

​Snapshot.Create()

​Snapshot.Open()

​Snapshot.Get()

​Snapshot.List()

​Snapshot.ListDir()

​Snapshot.Remove()

​Snapshot.Reindex()

​Snapshot.Save()

​Snapshot.Load()

​SandboxHandle methods

​h.Snapshot()

​SnapshotArtifact methods

​s.Verify()

​s.Path()

​s.Digest()

​s.SizeBytes()

​s.ImageRef()

​s.ImageManifestDigest()

​s.Format()

​s.Scope()

​s.Fstype()

​s.Parent()

​s.CreatedAt()

​s.Labels()

​s.SourceSandbox()

​SnapshotHandle methods

​h.Open()

​h.Remove()

​h.Digest()

​h.Name()

​h.ParentDigest()

​h.ImageRef()

​h.Format()

​h.Scope()

​h.SizeBytes()

​h.Path()

​h.CreatedAt()

​Types

​SnapshotArtifactstruct

​SnapshotHandlestruct

​SnapshotCreateOptionsstruct

​SnapshotSaveOptionsstruct

​SnapshotVerifyReportstruct

​SnapshotUpperVerifyStatusstruct

​Snapshot scope constants

Snapshot functions

Snapshot.Create()

Snapshot.Open()

Snapshot.Get()

Snapshot.List()

Snapshot.ListDir()

Snapshot.Remove()

Snapshot.Reindex()

Snapshot.Save()

Snapshot.Load()

SandboxHandle methods

h.Snapshot()

SnapshotArtifact methods

s.Verify()

s.Path()

s.Digest()

s.SizeBytes()

s.ImageRef()

s.ImageManifestDigest()

s.Format()

s.Scope()

s.Fstype()

s.Parent()

s.CreatedAt()

s.Labels()

s.SourceSandbox()

SnapshotHandle methods

h.Open()

h.Remove()

h.Digest()

h.Name()

h.ParentDigest()

h.ImageRef()

h.Format()

h.Scope()

h.SizeBytes()

h.Path()

h.CreatedAt()

Types

SnapshotArtifactstruct

SnapshotHandlestruct

SnapshotCreateOptionsstruct

SnapshotSaveOptionsstruct

SnapshotVerifyReportstruct

SnapshotUpperVerifyStatusstruct

Snapshot scope constants