Snapshots - microsandbox

Disk-only snapshots of a sandbox that is not running. Local snapshots are portable artifacts; cloud snapshots use managed storage or the organization’s host volume. See Snapshots for concepts and walkthroughs.

Snapshots are disk-only and require a sandbox that is stopped or crashed. ListDir, Reindex, Save/SaveTo, Load, and Verify retain the same API on every backend, but currently return ErrUnsupportedOperation in cloud.

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. With no DestDir, local uses its default snapshot directory and cloud uses managed storage. DestDir selects a local parent or cloud host-volume directory.

Parameters

ctxcontext.Context

Cancellation and deadline.

optsSnapshotCreateOptions

Name, source sandbox, labels, and integrity options.

Returns

*SnapshotArtifact

The created local or cloud snapshot.

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 snapshot using a backend-relative string. Bare values identify managed snapshots in cloud; path-like values identify host-volume artifacts.

Parameters

ctxcontext.Context

Cancellation and deadline.

pathOrNamestring

Backend-relative snapshot name, ID, or path.

Returns

*SnapshotArtifact

The opened local or cloud snapshot.

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 through the active backend.

Parameters

ctxcontext.Context

Cancellation and deadline.

nameOrDigeststring

Public identifier understood by the active backend, such as a local name/digest or cloud snapshot ID.

Returns

*SnapshotHandle

Lightweight handle returned by the active backend.

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 snapshots visible through the active backend. Cloud lists managed snapshots; host-volume artifacts are opened explicitly by reference.

Returns

[]*SnapshotHandle

All indexed handles.

Snapshot.ListDir()

func (snapshotFactory) ListDir(ctx context.Context, dir string) ([]*SnapshotArtifact, error)

Walk a local directory and parse each subdirectory’s manifest without touching the local index. Cloud returns ErrUnsupportedOperation.

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 through the active backend. Locally, removal also updates the index and refuses 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. Cloud returns ErrUnsupportedOperation.

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 local snapshot into a .tar.zst archive at outPath. Set SnapshotSaveOptions.PlainTar to skip compression. Cloud returns ErrUnsupportedOperation.

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 local snapshots directory or an explicit dest directory. Pass "" for the default destination. Cloud returns ErrUnsupportedOperation.

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. Local uses its default snapshot directory; cloud uses managed storage. The sandbox must be stopped or crashed.

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

A local or cloud disk snapshot. The accessors below are plain field reads.

s.SaveTo()

func (s *SnapshotArtifact) SaveTo(
    ctx context.Context,
    outPath string,
    opts SnapshotSaveOptions,
) error

Bundle this snapshot through the active backend while preserving its typed identifier-or-path reference. Cloud returns ErrUnsupportedOperation.

err := snap.SaveTo(ctx, "/tmp/snap.tar.zst", m.SnapshotSaveOptions{
    WithImage: true,
})

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

func (s *SnapshotArtifact) Reference() string

Stable backend-relative value. Prefer passing the SnapshotArtifact itself to WithFromSnapshot so its typed reference is preserved as well.

s.ReferenceKind()

func (s *SnapshotArtifact) ReferenceKind() string

Returns "id" or "path". Most callers can pass the artifact itself and never inspect this value.

s.Digest()

func (s *SnapshotArtifact) Digest() string

Canonical manifest digest (sha256:...).

s.SizeBytes()

func (s *SnapshotArtifact) SizeBytes() *uint64

Backend-reported stored payload 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 returned by the active backend. The handle retains a stable reference used by Open, Remove, and SaveTo.

h.Open()

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

Example

snap, err := h.Open(ctx)

Open the underlying snapshot metadata using this handle’s stable reference.

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 using this handle’s stable reference.

Parameters

ctxcontext.Context

Cancellation and deadline.

forcebool

Delete even if the snapshot has indexed children.

h.SaveTo()

func (h *SnapshotHandle) SaveTo(
    ctx context.Context,
    outPath string,
    opts SnapshotSaveOptions,
) error

Bundle the referenced snapshot through the active backend while preserving the handle’s typed identifier-or-path reference. Cloud returns ErrUnsupportedOperation.

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

Backend-reported stored payload size, or nil if unknown.

h.ReferenceKind()

func (h *SnapshotHandle) ReferenceKind() string

Returns "id" or "path" for the handle’s backend-neutral reference.

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 backend-neutral disk snapshot. Fields are unexported; read them through the accessor methods below.

Method	Returns	Description
`Reference()`	`string`	Stable backend-relative restore reference
`ReferenceKind()`	`string`	`id` or `path`
`Digest()`	`string`	Canonical manifest digest (`sha256:...`)
`SizeBytes()`	`*uint64`	Backend-reported stored payload size, when known
`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
`SaveTo(ctx, outPath, opts)`	`error`	Bundle using this snapshot’s typed reference
`Verify(ctx)`	`(*SnapshotVerifyReport, error)`	Recompute content integrity

SnapshotHandlestruct

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

A lightweight handle returned by the active backend. 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`	Backend-reported stored payload size
`Reference()`	`string`	Stable backend-relative restore reference
`ReferenceKind()`	`string`	`id` or `path`
`CreatedAt()`	`time.Time`	Snapshot creation time
`Open(ctx)`	`(*SnapshotArtifact, error)`	Open the artifact metadata
`Remove(ctx, force)`	`error`	Remove this snapshot
`SaveTo(ctx, outPath, opts)`	`error`	Bundle using this handle’s typed reference

SnapshotCreateOptionsstruct

Accepted by Snapshot.Create()

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

Field	Type	Description
Name	`string`	Snapshot name; storage location is selected by the active backend
FromSandbox	`string`	Name of the stopped or crashed sandbox to capture
DestDir	`string`	Local parent or cloud host-volume directory; empty = backend-managed storage
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() and instance SaveTo() methods

Configures Snapshot.Save and instance SaveTo() methods.

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

​s.Verify()

​s.Reference()

​s.ReferenceKind()

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

​h.Digest()

​h.Name()

​h.ParentDigest()

​h.ImageRef()

​h.Format()

​h.Scope()

​h.SizeBytes()

​h.ReferenceKind()

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

s.Verify()

s.Reference()

s.ReferenceKind()

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

h.Digest()

h.Name()

h.ParentDigest()

h.ImageRef()

h.Format()

h.Scope()

h.SizeBytes()

h.ReferenceKind()

h.CreatedAt()

Types

SnapshotArtifactstruct

SnapshotHandlestruct

SnapshotCreateOptionsstruct

SnapshotSaveOptionsstruct

SnapshotVerifyReportstruct

SnapshotUpperVerifyStatusstruct

Snapshot scope constants