Run & teardown

runInSandbox handles launch + cleanup for one-off workloads.

For one-off workloads — a build, a test, a single agent invocation — runInSandbox scopes the sandbox to a callback. It boots the VM, runs your function, and stops the VM in a finally block, so cleanup happens even if your code throws.

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 is already stopped by the time this prints.

The callback’s return value is runInSandbox’s return value, so you can build pipelines:

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

const versions = await runInSandbox(
  { snapshot: "lightbox", name: "scratch" },
  async (sb) => {
    const cliVersions: Record<string, string> = {};
    for (const cli of ["copilot", "gemini", "codex", "pi"]) {
      const r = await sb.shell(`${cli} --version 2>&1 | head -1`);
      cliVersions[cli] = r.stdout().trim();
    }
    return cliVersions;
  },
);
console.log(versions);