Snapshots - microsandbox

Create and manage disk-only snapshots of stopped sandboxes. See Snapshots for usage and lifecycle concepts.

Snapshot

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

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

struct

Returned by Snapshot.Create() · Snapshot.Open() · Snapshot.ListDir() · h.Snapshot() · h.Open()

A snapshot artifact on disk.

s.Verify()

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

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

Returns

*SnapshotVerifyReport

Recomputed digest and upper-layer status.

Example

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

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

struct

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

A snapshot handle backed by the local index.

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.

Constants

Snapshot scopes

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)

Types

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

​Snapshot.Create()

​Snapshot.Open()

​Snapshot.Get()

​Snapshot.List()

​Snapshot.ListDir()

​Snapshot.Remove()

​Snapshot.Reindex()

​Snapshot.Save()

​Snapshot.Load()

​SandboxHandle

​h.Snapshot()

​SnapshotArtifact

​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

​h.Open()

​h.Remove()

​h.Digest()

​h.Name()

​h.ParentDigest()

​h.ImageRef()

​h.Format()

​h.Scope()

​h.SizeBytes()

​h.Path()

​h.CreatedAt()

​Constants

​Types

​SnapshotCreateOptionsstruct

​SnapshotSaveOptionsstruct

​SnapshotVerifyReportstruct

​SnapshotUpperVerifyStatusstruct

Snapshot

Snapshot.Create()

Snapshot.Open()

Snapshot.Get()

Snapshot.List()

Snapshot.ListDir()

Snapshot.Remove()

Snapshot.Reindex()

Snapshot.Save()

Snapshot.Load()

SandboxHandle

h.Snapshot()

SnapshotArtifact

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

h.Open()

h.Remove()

h.Digest()

h.Name()

h.ParentDigest()

h.ImageRef()

h.Format()

h.Scope()

h.SizeBytes()

h.Path()

h.CreatedAt()

Constants

Types

SnapshotCreateOptionsstruct

SnapshotSaveOptionsstruct

SnapshotVerifyReportstruct

SnapshotUpperVerifyStatusstruct