Snapshots - microsandbox

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

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

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

Example

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

Create a snapshot from a stopped or crashed sandbox. Set exactly one of SnapshotCreateOptions.Name (resolved under the default snapshots directory) or SnapshotCreateOptions.Path (an explicit artifact directory).

Parameters

ctxcontext.Context

Cancellation and deadline.

sourceSandboxstring

Name of the stopped or crashed sandbox to snapshot.

optsSnapshotCreateOptions

Destination, labels, and integrity options.

Returns

*SnapshotArtifact

The created artifact on disk.

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

func (snapshotFactory) Export(ctx context.Context, nameOrPath, outPath string, opts SnapshotExportOptions) error

Example

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

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

Parameters

ctxcontext.Context

Cancellation and deadline.

nameOrPathstring

Bare name or artifact path to export.

outPathstring

Destination archive path.

optsSnapshotExportOptions

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

Snapshot.Import()

func (snapshotFactory) Import(ctx context.Context, archive, dest string) (*SnapshotHandle, error)

Example

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

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

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)

Example

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

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

*SnapshotArtifact

The created artifact.

h.SnapshotTo()

func (h *SandboxHandle) SnapshotTo(ctx context.Context, path string) (*SnapshotArtifact, error)

Example

snap, err := h.SnapshotTo(ctx, "/srv/snapshots/baseline")

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

*SnapshotArtifact

The created artifact.

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)

Example

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

Recompute recorded content integrity for this snapshot. Requires that the artifact was created with RecordIntegrity set.

Returns

*SnapshotVerifyReport

Recomputed digest and upper-layer status.

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.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.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.SnapshotTo() · 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"`
`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.Import()

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"`
`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. 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` can recompute them later

SnapshotExportOptionsstruct

Accepted by Snapshot.Export()

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

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 functions

​Snapshot.Create()

​Snapshot.Open()

​Snapshot.Get()

​Snapshot.List()

​Snapshot.ListDir()

​Snapshot.Remove()

​Snapshot.Reindex()

​Snapshot.Export()

​Snapshot.Import()

​SandboxHandle methods

​h.Snapshot()

​h.SnapshotTo()

​SnapshotArtifact methods

​s.Verify()

​s.Path()

​s.Digest()

​s.SizeBytes()

​s.ImageRef()

​s.ImageManifestDigest()

​s.Format()

​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.SizeBytes()

​h.Path()

​h.CreatedAt()

​Types

​SnapshotArtifactstruct

​SnapshotHandlestruct

​SnapshotCreateOptionsstruct

​SnapshotExportOptionsstruct

​SnapshotVerifyReportstruct

​SnapshotUpperVerifyStatusstruct

Snapshot functions

Snapshot.Create()

Snapshot.Open()

Snapshot.Get()

Snapshot.List()

Snapshot.ListDir()

Snapshot.Remove()

Snapshot.Reindex()

Snapshot.Export()

Snapshot.Import()

SandboxHandle methods

h.Snapshot()

h.SnapshotTo()

SnapshotArtifact methods

s.Verify()

s.Path()

s.Digest()

s.SizeBytes()

s.ImageRef()

s.ImageManifestDigest()

s.Format()

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

h.Path()

h.CreatedAt()

Types

SnapshotArtifactstruct

SnapshotHandlestruct

SnapshotCreateOptionsstruct

SnapshotExportOptionsstruct

SnapshotVerifyReportstruct

SnapshotUpperVerifyStatusstruct