Launch a sandbox

launchSandbox() returns a live handle; runInSandbox() scopes one to a callback.

launchSandbox(opts) → Promise<Sandbox>

Boots a sandbox from a snapshot and returns the live Sandbox handle. Idempotent by default — wipes any existing sandbox of the same name first. Pass { overwrite: false } to make collisions throw.

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

const sb = await launchSandbox({
  snapshot: "lightbox",
  name: "agent-1",
  resources: { cpus: 2, memory: "2G" },
});

const out = await sb.exec("copilot", ["--version"]);
console.log(out.stdout());

await sb.detach();   // VM keeps running after this script exits
// or: await sb.stop();    to shut it down now

runInSandbox(opts, fn) → Promise<T>

function runInSandbox<T>(
  opts: LaunchOptions,
  fn: (sb: Sandbox) => Promise<T>,
): Promise<T>;

Launch a sandbox, run a callback against it, then stop it — even if the callback throws. Returns whatever the callback returns. Replaces the await using pattern and the try { ... } finally { sb.stop() } boilerplate.

import { runInSandbox } from "@beamhop/lightbox";

const out = await runInSandbox(
  { snapshot: "lightbox", name: "ephemeral" },
  (sb) => sb.shell("pi --version && copilot --version"),
);
console.log(out.stdout());
// Sandbox already stopped by the time we get here.

LaunchOptions