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 TypeScript SDK reference.
import { Sandbox, Snapshot, SnapshotHandle } from "microsandbox";
import type { ExportOpts, SnapshotVerifyReport } from "microsandbox";
Snapshots are disk-only and stopped-only. Live snapshots and qcow2 backing chains are tracked as future work.
SandboxBuilder
fromSnapshot()
fromSnapshot(pathOrName: string): SandboxBuilder
image() — the snapshot already pins the image.
Parameters
| Name | Type | Description |
|---|
| pathOrName | string | Bare name (resolved under ~/.microsandbox/snapshots/) or filesystem path to an artifact directory |
SandboxHandle methods
snapshot()
snapshot(name: string): Promise<Snapshot>
~/.microsandbox/snapshots/<name>/). For an explicit filesystem destination, see snapshotTo().
Errors
SnapshotSandboxRunning — the sandbox is not stoppedSnapshotAlreadyExists — destination exists (use the builder with .force() to overwrite)
snapshotTo()
snapshotTo(path: string): Promise<Snapshot>
Snapshot (instance)
path
Path to the artifact directory.
digest
Canonical content digest (sha256:hex) over the manifest bytes. The snapshot’s identity.
sizeBytes
readonly sizeBytes: bigint
imageRef
readonly imageRef: string
imageManifestDigest
readonly imageManifestDigest: string
readonly format: "raw" | "qcow2"
"raw" today.
fstype
Filesystem type inside the upper (e.g. "ext4").
parent
readonly parent: string | null
null for a root.
createdAt
readonly createdAt: string
labels
readonly labels: ReadonlyArray<readonly [string, string]>
verify()
verify(): Promise<SnapshotVerifyReport>
const report = await snap.verify();
if (report.upper.kind === "verified") {
console.log(`hash matches: ${report.upper.digest}`);
} else {
console.log("no integrity hash recorded");
}
Snapshot.builder()
static builder(sourceSandbox: string): SnapshotBuilder
const snap = await Snapshot.builder("baseline")
.name("after-pip-install") // bare name in default dir
.label("stage", "post-deps")
.force() // overwrite if it exists
.recordIntegrity() // hash the upper layer
.create();
| Method | Description |
|---|
.name(string) | Bare name under the default snapshots directory |
.path(string) | Explicit filesystem path |
.label(key, value) | Add a key=value label (may be repeated) |
.force() | Overwrite an existing artifact at the destination |
.recordIntegrity() | Compute and record a content-integrity hash at creation |
.build() | Snapshot the accumulated configuration |
.create() | Build and execute |
Snapshot (static)
Snapshot.open()
static open(pathOrName: string): Promise<Snapshot>
verify() for content checks.
Snapshot.get()
static get(nameOrDigest: string): Promise<SnapshotHandle>
Snapshot.list()
static list(): Promise<SnapshotHandle[]>
Snapshot.listDir()
static listDir(dir: string): Promise<Snapshot[]>
Snapshot.remove()
static remove(pathOrName: string, opts?: { force?: boolean }): Promise<void>
force: true.
Snapshot.reindex()
static reindex(dir?: string): Promise<number>
dir (default: configured snapshots dir) and rebuild the local index. Returns the number of artifacts indexed.
Snapshot.export()
static export(nameOrPath: string, out: string, opts?: ExportOpts): Promise<void>
.tar.zst archive. Computes and embeds the integrity hash in the bundled manifest if not already present.
ExportOpts
| Field | Type | Description |
|---|
withParents | boolean | Walk the parent chain (no-op today) |
withImage | boolean | Bundle the OCI image cache for offline transport |
plainTar | boolean | Skip zstd compression and write a plain .tar |
Snapshot.import()
static import(archive: string, dest?: string): Promise<SnapshotHandle>
.tar.zst or .tar) into the snapshots directory, verifying recorded integrity on the way in. Compression is detected from magic bytes.
SnapshotHandle
Lightweight handle backed by an index row. Returned by Snapshot.list() and Snapshot.get().
const h = await Snapshot.get("after-pip-install");
h.digest; // string ("sha256:...")
h.name; // string | null
h.parentDigest; // string | null — null today
h.imageRef; // string
h.format; // "raw" | "qcow2"
h.sizeBytes; // bigint | null
h.createdAt; // Date
h.path; // string
const snap = await h.open(); // metadata-validated
await h.remove({ force: false }); // refuse if has children
Types
export interface ExportOpts {
withParents?: boolean;
withImage?: boolean;
plainTar?: boolean;
}
export type SnapshotVerifyReport =
| { digest: string; path: string; upper: { kind: "notRecorded" } }
| { digest: string; path: string;
upper: { kind: "verified"; algorithm: string; digest: string } };
