Documentation Index
Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
Use this file to discover all available pages before exploring further.
Disk-only snapshots of a stopped sandbox. See Snapshots for concepts and walkthroughs; this page is the Go SDK reference.
import m "github.com/superradcompany/microsandbox/sdk/go"
Snapshots are disk-only and stopped-only. Live snapshots and qcow2 backing chains are tracked as future work.
Boot from snapshot
Pass WithSnapshot to CreateSandbox. It is mutually exclusive with WithImage.
sb, err := m.CreateSandbox(ctx, "worker",
m.WithSnapshot("after-pip-install"),
)
WithSnapshot()
func WithSnapshot(pathOrName string) SandboxOption
~/.microsandbox/snapshots/) or filesystem path.
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")
Snapshot()
func (h *SandboxHandle) Snapshot(ctx context.Context, name string) (*SnapshotArtifact, error)
SnapshotTo()
func (h *SandboxHandle) SnapshotTo(ctx context.Context, path string) (*SnapshotArtifact, error)
Snapshot
Helpers for snapshot artifact operations. Access via the package-level Snapshot value.
Snapshot.Create()
func (snapshotFactory) Create(
ctx context.Context,
sourceSandbox string,
opts SnapshotCreateOptions,
) (*SnapshotArtifact, error)
SnapshotCreateOptions.Name or SnapshotCreateOptions.Path.
snap, err := m.Snapshot.Create(ctx, "baseline",
m.SnapshotCreateOptions{
Name: "after-pip-install",
Labels: map[string]string{"stage": "post-deps"},
RecordIntegrity: true,
},
)
Snapshot.Open()
func (snapshotFactory) Open(ctx context.Context, pathOrName string) (*SnapshotArtifact, error)
Verify for content checks.
Snapshot.Get()
func (snapshotFactory) Get(ctx context.Context, nameOrDigest string) (*SnapshotHandle, error)
Snapshot.List()
func (snapshotFactory) List(ctx context.Context) ([]*SnapshotHandle, error)
Snapshot.ListDir()
func (snapshotFactory) ListDir(ctx context.Context, dir string) ([]*SnapshotArtifact, error)
Snapshot.Remove()
func (snapshotFactory) Remove(ctx context.Context, pathOrName string, force bool) error
force is true.
Snapshot.Reindex()
func (snapshotFactory) Reindex(ctx context.Context, dir string) (uint32, error)
dir and rebuild the local index. Returns the number of artifacts indexed.
Snapshot.Export()
func (snapshotFactory) Export(
ctx context.Context,
nameOrPath string,
outPath string,
opts SnapshotExportOptions,
) error
.tar.zst archive. Set PlainTar to skip compression.
Snapshot.Import()
func (snapshotFactory) Import(ctx context.Context, archive, dest string) (*SnapshotHandle, error)
dest directory. Pass "" for the default destination.
SnapshotArtifact
An artifact on disk, returned by Snapshot.Create, Snapshot.Open, Snapshot.ListDir, and SandboxHandle.Snapshot.
| 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()
func (s *SnapshotArtifact) Verify(ctx context.Context) (*SnapshotVerifyReport, error)
SnapshotHandle
Lightweight handle backed by the local index. Returned by Snapshot.Get, Snapshot.List, and Snapshot.Import.
| 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 |
CreatedAt() | time.Time | Snapshot creation time |
Path() | string | Artifact directory |
Open(ctx) | (*SnapshotArtifact, error) | Open the artifact metadata |
Remove(ctx, force) | error | Remove this snapshot |
Types
type SnapshotCreateOptions struct {
Name string
Path string
Labels map[string]string
Force bool
RecordIntegrity bool
}
type SnapshotExportOptions struct {
WithParents bool
WithImage bool
PlainTar bool
}
type SnapshotVerifyReport struct {
Digest string
Path string
Upper SnapshotUpperVerifyStatus
}
type SnapshotUpperVerifyStatus struct {
Kind string
Algorithm string
Digest string
}
