lightbox

Getting Started

Install lightbox and build your first snapshot in 90 seconds.

Install

Install directly from the GitHub repository:

npm install github:beamhop/lightbox

npm install runs the package’s prepare script, which compiles the library on your machine. Requires Node ≥ 18 (Bun also works).

Build a snapshot

// build.ts
import { buildSnapshot } from "@beamhop/lightbox";

await buildSnapshot({
  name: "my-snap",
  image: "oven/bun",
  setup: [
    "bun i -g @earendil-works/pi-coding-agent",   // string shorthand
  ],
});

Snapshots live under ~/.microsandbox/snapshots/. Re-running this script is safe — buildSnapshot overwrites the existing snapshot by default.

Run something in a sandbox

// run.ts
import { runInSandbox } from "@beamhop/lightbox";

const out = await runInSandbox(
  { snapshot: "my-snap", name: "agent-1" },
  (sb) => sb.exec("pi", ["--version"]),
);
console.log(out.stdout());

runInSandbox boots the VM, runs your callback, and stops the VM — even if the callback throws. Boots in under 100 ms because the snapshot’s upper layer is pre-populated.

Detached sandboxes

If you want the VM to outlive your script (so you can connect from a different process), use launchSandbox and detach the handle yourself:

import { launchSandbox, connectToSandbox } from "@beamhop/lightbox";

const sb = await launchSandbox({ snapshot: "my-snap", name: "agent-1" });
await sb.detach();   // VM keeps running after process exit

// Later, from any other process:
const live = await connectToSandbox("agent-1");
console.log((await live.shell("pi --version")).stdout());

Next steps

  • API reference — every export in lightbox.
  • Examples — worked end-to-end scripts.
  • Concepts — snapshots, builder VMs, and the lifecycle model.