docs/sdk/go/snapshots.mdx
Create and manage disk-only snapshots of stopped sandboxes. See Snapshots for usage and lifecycle concepts.
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, 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.
snap, err := m.Snapshot.Create(ctx, m.SnapshotCreateOptions{
Name: "after-pip-install",
FromSandbox: "baseline",
Labels: map[string]string{"stage": "post-deps"},
RecordIntegrity: true,
})
func (snapshotFactory) Open(ctx context.Context, pathOrName string) (*SnapshotArtifact, error)
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.
func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)
h, err := m.Snapshot.Get(ctx, "after-pip-install")
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>func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)
handles, err := m.Snapshot.List(ctx)
for _, h := range handles {
fmt.Println(h.Digest(), h.ImageRef())
}
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>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
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.
func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)
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.
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.
err := m.Snapshot.Save(ctx, "after-pip-install", "/tmp/snap.tar.zst",
m.SnapshotSaveOptions{WithParents: true},
)
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.
h, err := m.Snapshot.Load(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. To place the artifact elsewhere, use Snapshot.Save / Snapshot.Load or move the self-contained artifact directory.
snap, err := h.Snapshot(ctx, "after-pip-install")
A snapshot artifact on disk.
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.
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)
}
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) Scope() string
Snapshot scope: SnapshotScopeDisk ("disk") or SnapshotScopeResumable ("resumable"). Always SnapshotScopeDisk today; SnapshotScopeResumable is reserved for resumable snapshots.
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 snapshot handle backed by the local index.
func (h *SnapshotHandle) Open(ctx context.Context) (*SnapshotArtifact, error)
snap, err := h.Open(ctx)
Open the underlying artifact metadata. Equivalent to Snapshot.Open on this handle's path.
func (h *SnapshotHandle) Remove(ctx context.Context, force bool) error
err := h.Remove(ctx, false)
Remove this snapshot. Equivalent to Snapshot.Remove on this handle's digest.
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) Scope() string
Snapshot scope: SnapshotScopeDisk ("disk") or SnapshotScopeResumable ("resumable"). Always SnapshotScopeDisk today.
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.
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) |
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 |
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 |
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 |