docs/sdk/go/snapshots.mdx
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.
<Note> Snapshots are **disk-only** and require a sandbox that is stopped or crashed. </Note> <div className="msb-glance"> <p className="msb-gl"><span className="msb-dot static"></span>Functions · Snapshot<span className="msb-ct">9</span></p> <a className="msb-row" href="#snapshot-create"><span className="msb-rn">Snapshot.Create()</span><span className="msb-rg">snapshot a stopped sandbox</span></a> <a className="msb-row" href="#snapshot-open"><span className="msb-rn">Snapshot.Open()</span><span className="msb-rg">open an artifact by name/path</span></a> <a className="msb-row" href="#snapshot-get"><span className="msb-rn">Snapshot.Get()</span><span className="msb-rg">index handle by name/digest</span></a> <a className="msb-row" href="#snapshot-list"><span className="msb-rn">Snapshot.List()</span><span className="msb-rg">indexed snapshots</span></a> <a className="msb-row" href="#snapshot-listdir"><span className="msb-rn">Snapshot.ListDir()</span><span className="msb-rg">walk a directory</span></a> <a className="msb-row" href="#snapshot-remove"><span className="msb-rn">Snapshot.Remove()</span><span className="msb-rg">delete artifact + index row</span></a> <a className="msb-row" href="#snapshot-reindex"><span className="msb-rn">Snapshot.Reindex()</span><span className="msb-rg">rebuild the local index</span></a> <a className="msb-row" href="#snapshot-export"><span className="msb-rn">Snapshot.Export()</span><span className="msb-rg">bundle into an archive</span></a> <a className="msb-row" href="#snapshot-import"><span className="msb-rn">Snapshot.Import()</span><span className="msb-rg">unpack an archive</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Methods · *SandboxHandle<span className="msb-ct">2</span></p> <a className="msb-row" href="#h-snapshot"><span className="msb-rn">h.Snapshot()</span><span className="msb-rg">snapshot to a bare name</span></a> <a className="msb-row" href="#h-snapshotto"><span className="msb-rn">h.SnapshotTo()</span><span className="msb-rg">snapshot to a directory</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Methods · *SnapshotArtifact<span className="msb-ct">12</span></p> <a className="msb-row" href="#s-verify"><span className="msb-rn">s.Verify()</span><span className="msb-rg">recompute content integrity</span></a> <a className="msb-row" href="#s-path"><span className="msb-rn">s.Path()</span><span className="msb-rg">artifact directory</span></a> <a className="msb-row" href="#s-digest"><span className="msb-rn">s.Digest()</span><span className="msb-rg">manifest digest</span></a> <a className="msb-row" href="#s-sizebytes"><span className="msb-rn">s.SizeBytes()</span><span className="msb-rg">upper-layer size</span></a> <a className="msb-row" href="#s-imageref"><span className="msb-rn">s.ImageRef()</span><span className="msb-rg">source image reference</span></a> <a className="msb-row" href="#s-imagemanifestdigest"><span className="msb-rn">s.ImageManifestDigest()</span><span className="msb-rg">pinned OCI manifest digest</span></a> <a className="msb-row" href="#s-format"><span className="msb-rn">s.Format()</span><span className="msb-rg">raw or qcow2</span></a> <a className="msb-row" href="#s-fstype"><span className="msb-rn">s.Fstype()</span><span className="msb-rg">upper filesystem type</span></a> <a className="msb-row" href="#s-parent"><span className="msb-rn">s.Parent()</span><span className="msb-rg">parent digest, or nil</span></a> <a className="msb-row" href="#s-createdat"><span className="msb-rn">s.CreatedAt()</span><span className="msb-rg">RFC 3339 timestamp</span></a> <a className="msb-row" href="#s-labels"><span className="msb-rn">s.Labels()</span><span className="msb-rg">user labels</span></a> <a className="msb-row" href="#s-sourcesandbox"><span className="msb-rn">s.SourceSandbox()</span><span className="msb-rg">source sandbox name</span></a> <p className="msb-gl"><span className="msb-dot instance"></span>Methods · *SnapshotHandle<span className="msb-ct">10</span></p> <a className="msb-row" href="#h-open"><span className="msb-rn">h.Open()</span><span className="msb-rg">open the artifact</span></a> <a className="msb-row" href="#h-remove"><span className="msb-rn">h.Remove()</span><span className="msb-rg">delete this snapshot</span></a> <a className="msb-row" href="#h-digest"><span className="msb-rn">h.Digest()</span><span className="msb-rg">manifest digest</span></a> <a className="msb-row" href="#h-name"><span className="msb-rn">h.Name()</span><span className="msb-rg">bare-name alias, or nil</span></a> <a className="msb-row" href="#h-parentdigest"><span className="msb-rn">h.ParentDigest()</span><span className="msb-rg">parent digest, or nil</span></a> <a className="msb-row" href="#h-imageref"><span className="msb-rn">h.ImageRef()</span><span className="msb-rg">pinned image reference</span></a> <a className="msb-row" href="#h-format"><span className="msb-rn">h.Format()</span><span className="msb-rg">raw or qcow2</span></a> <a className="msb-row" href="#h-sizebytes"><span className="msb-rn">h.SizeBytes()</span><span className="msb-rg">upper size at index time</span></a> <a className="msb-row" href="#h-path"><span className="msb-rn">h.Path()</span><span className="msb-rg">artifact directory</span></a> <a className="msb-row" href="#h-createdat"><span className="msb-rn">h.CreatedAt()</span><span className="msb-rg">creation time</span></a> <p className="msb-gl"><span className="msb-dot static"></span>Options<span className="msb-ct">1</span></p> <div className="msb-chiprow"> <a className="msb-chip" href="/sdk/go/sandbox#withsnapshot">WithSnapshot()</a> </div> <p className="msb-gl"><span className="msb-dot type"></span>Types</p> <div className="msb-chiprow"> <a className="msb-typepill" href="#snapshotartifactstruct">SnapshotArtifact</a> <a className="msb-typepill" href="#snapshothandlestruct">SnapshotHandle</a> <a className="msb-typepill" href="#snapshotcreateoptionsstruct">SnapshotCreateOptions</a> <a className="msb-typepill" href="#snapshotexportoptionsstruct">SnapshotExportOptions</a> <a className="msb-typepill" href="#snapshotverifyreportstruct">SnapshotVerifyReport</a> <a className="msb-typepill" href="#snapshotupperverifystatusstruct">SnapshotUpperVerifyStatus</a> </div> </div> <p className="msb-label" id="typical-flow">Typical flow</p>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"),
)
Package-level helpers for snapshot artifacts. Access them through the exported Snapshot value, e.g. m.Snapshot.Create(ctx, ...).
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 (resolved under the default snapshots directory) or SnapshotCreateOptions.Path (an explicit artifact directory).
snap, err := m.Snapshot.Create(ctx, "baseline", m.SnapshotCreateOptions{
Name: "after-pip-install",
Labels: map[string]string{"stage": "post-deps"},
RecordIntegrity: true,
})
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() for content checks.
snap, err := m.Snapshot.Open(ctx, "after-pip-install")
func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)
Look up a lightweight handle in the local index by name, digest, or path.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancellation and deadline.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>nameOrDigest</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Bare name, manifest digest, or artifact path.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshothandlestruct">*SnapshotHandle</a></div> <div className="msb-param-desc">Index-backed handle.</div> </div> </div> <Accordion title="Example">h, err := m.Snapshot.Get(ctx, "after-pip-install")
func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)
List indexed snapshots from the local DB cache.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshothandlestruct">[]*SnapshotHandle</a></div> <div className="msb-param-desc">All indexed handles.</div> </div> </div> <Accordion title="Example">handles, err := m.Snapshot.List(ctx)
for _, h := range handles {
fmt.Println(h.Digest(), h.ImageRef())
}
func (snapshotFactory) ListDir(ctx context.Context, dir string) ([]*SnapshotArtifact, error)
Walk a directory and parse each subdirectory's manifest without touching the index.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancellation and deadline.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>dir</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Directory holding snapshot artifact subdirectories.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">[]*SnapshotArtifact</a></div> <div className="msb-param-desc">One artifact per parsed subdirectory.</div> </div> </div>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.
err := m.Snapshot.Remove(ctx, "after-pip-install", false)
func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)
Walk dir and rebuild the local index from the artifacts it finds.
n, err := m.Snapshot.Reindex(ctx, "/srv/snapshots")
fmt.Printf("indexed %d snapshots\n", n)
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 to skip compression.
err := m.Snapshot.Export(ctx, "after-pip-install", "/tmp/snap.tar.zst",
m.SnapshotExportOptions{WithParents: true},
)
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.
h, err := m.Snapshot.Import(ctx, "/tmp/snap.tar.zst", "")
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")
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancellation and deadline.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Bare name for the artifact.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">*SnapshotArtifact</a></div> <div className="msb-param-desc">The created artifact.</div> </div> </div> <Accordion title="Example">snap, err := h.Snapshot(ctx, "after-pip-install")
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancellation and deadline.</div> </div> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div> <div className="msb-param-desc">Destination artifact directory.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshotartifactstruct">*SnapshotArtifact</a></div> <div className="msb-param-desc">The created artifact.</div> </div> </div> <Accordion title="Example">snap, err := h.SnapshotTo(ctx, "/srv/snapshots/baseline")
An artifact on disk. The accessors below are plain field reads; only Verify touches the filesystem.
func (s *SnapshotArtifact) Verify(ctx context.Context) (*SnapshotVerifyReport, error)
Recompute recorded content integrity for this snapshot. Requires that the artifact was created with RecordIntegrity set.
report, err := snap.Verify(ctx)
if err != nil {
return err
}
fmt.Println(report.Upper.Digest)
func (s *SnapshotArtifact) Path() string
Artifact directory on disk.
func (s *SnapshotArtifact) Digest() string
Canonical manifest digest (sha256:...).
func (s *SnapshotArtifact) SizeBytes() uint64
Apparent upper-layer size in bytes.
func (s *SnapshotArtifact) ImageRef() string
Image reference the snapshot was taken from.
func (s *SnapshotArtifact) ImageManifestDigest() string
Pinned OCI manifest digest of the base image.
func (s *SnapshotArtifact) Format() string
Upper-layer disk format: "raw" or "qcow2".
func (s *SnapshotArtifact) Fstype() string
Filesystem type inside the upper layer.
func (s *SnapshotArtifact) Parent() *string
Parent digest, or nil if this snapshot has no parent. Returns a defensive copy.
func (s *SnapshotArtifact) CreatedAt() string
RFC 3339 creation timestamp.
func (s *SnapshotArtifact) Labels() map[string]string
User labels recorded at creation. Returns a defensive copy.
func (s *SnapshotArtifact) SourceSandbox() *string
Best-effort source sandbox name, or nil. Returns a defensive copy.
A lightweight handle backed by the local index. The accessors below are plain field reads; Open and Remove take a context.
func (h *SnapshotHandle) Open(ctx context.Context) (*SnapshotArtifact, error)
Open the underlying artifact metadata. Equivalent to Snapshot.Open on this handle's path.
snap, err := h.Open(ctx)
func (h *SnapshotHandle) Remove(ctx context.Context, force bool) error
Remove this snapshot. Equivalent to Snapshot.Remove on this handle's digest.
err := h.Remove(ctx, false)
func (h *SnapshotHandle) Digest() string
Manifest digest.
func (h *SnapshotHandle) Name() *string
Bare-name alias, if the snapshot was indexed with one; otherwise nil. Returns a defensive copy.
func (h *SnapshotHandle) ParentDigest() *string
Parent digest, or nil. Returns a defensive copy.
func (h *SnapshotHandle) ImageRef() string
Pinned image reference.
func (h *SnapshotHandle) Format() string
Upper-layer disk format: "raw" or "qcow2".
func (h *SnapshotHandle) SizeBytes() *uint64
Apparent upper size at index time, or nil if unknown. Returns a defensive copy.
func (h *SnapshotHandle) Path() string
Artifact directory on disk.
func (h *SnapshotHandle) CreatedAt() time.Time
Snapshot creation time, decoded from the index's Unix timestamp.
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 |
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 |
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 |
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 |
Result of Verify.
| Field | Type | Description |
|---|---|---|
| Digest | string | Recomputed manifest digest |
| Path | string | Artifact directory that was verified |
| Upper | SnapshotUpperVerifyStatus | Upper-layer integrity status |
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 |