API Reference

The lightbox TypeScript library — typed snapshot builder and sandbox launcher.

The API is organized around the two things lightbox manages: snapshots (frozen disk images) and sandboxes (microVMs you boot from them), plus volumes for shared persistent storage.

If the snapshot/sandbox distinction is new, read Concepts first — it’s the 3-minute orientation.

Install

npm install github:beamhop/lightbox

microsandbox is the only runtime dep. It pulls the platform-appropriate msb + libkrunfw binaries on first use (cached under ~/.microsandbox/). No global tools required.

Snapshots

The frozen disk images sandboxes boot from. Built once, reused forever. Like Docker images.

• Create — buildSnapshot(), defineSnapshot(), setup steps, codingAgentsPreset
• List & inspect — listSnapshots(), snapshotExists()
• Delete — removeSnapshot()

Sandboxes

The running microVMs. Like Docker containers, but each in its own kernel and booting in under 100 ms.

• Launch — launchSandbox(), runInSandbox()
• Execute commands — sb.exec, sb.shell, streaming, attachShell, filesystem access
• List & connect — Sandbox.list(), connectToSandbox()
• Stop & delete — sb.stop(), sb.detach(), removeSandbox()

Volumes & mounts

Persistent storage attached to sandboxes — caches, model weights, shared scratch space.

• Overview & mount syntax — the mounts option on launchSandbox
• Lifecycle — ensureVolume, listVolumes, removeVolume

Reference

• Types — every public type exported by lightbox
• SDK re-exports — Sandbox, Snapshot, Volume, ExecHandle, ExecOutput