SDK re-exports

Classes and types re-exported from the underlying microsandbox SDK.

For convenience, lightbox re-exports the runtime classes and types that callers most often need from the underlying microsandbox Node SDK — so you don’t need a second import.

import {
  Sandbox,        // runtime class — .get, .list, .builder, .remove
  Snapshot,       // runtime class — .builder, .list, .get
  Volume,         // runtime class — .builder, .list, .get
  VolumeHandle,   // returned by Volume.get / Volume.list entries
} from "@beamhop/lightbox";

import type {
  ExecHandle,     // streaming exec — yields ExecEvent
  ExecOutput,     // one-shot exec result
} from "@beamhop/lightbox";

Anything not re-exported (e.g. SandboxBuilder for advanced configuration, SnapshotBuilder, the Patch API) can still be imported from microsandbox directly — it’s a regular dependencies entry of @beamhop/lightbox.

Sandbox

The fluent builder API surface used internally by launchSandbox. You’d reach for Sandbox directly only when you need a setting lightbox doesn’t expose — e.g. SDK-level features like Sandbox.builder(name).disableNetwork() or .secret(...). The methods you’ll see on a live handle (exec, shell, attachShell, fs, stop, detach, etc.) are documented in Execute commands.

class Sandbox {
  static builder(name: string): SandboxBuilder;
  static get(name: string): Promise<SandboxHandle>;
  static list(): Promise<SandboxHandle[]>;
  static remove(name: string): Promise<void>;

  exec(cmd: string, args?: Iterable<string>): Promise<ExecOutput>;
  shell(script: string): Promise<ExecOutput>;
  execStream(cmd: string, args?: Iterable<string>): Promise<ExecHandle>;
  shellStream(script: string): Promise<ExecHandle>;
  attachShell(): Promise<number>;
  fs(): SandboxFs;
  stop(): Promise<void>;
  stopAndWait(): Promise<ExitStatus>;
  kill(): Promise<void>;
  detach(): Promise<void>;
  // ...
}

Snapshot

You rarely need this directly — buildSnapshot wraps Snapshot.builder, and listSnapshots wraps Snapshot.list.

class Snapshot {
  static builder(sourceSandbox: string): SnapshotBuilder;
  static get(nameOrDigest: string): Promise<SnapshotHandle>;
  static list(): Promise<SnapshotHandle[]>;
}

Volume / VolumeHandle

Useful for host-side filesystem access into a named volume — read/write/list files without booting a sandbox to do it.

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

const handle = await Volume.get("npm-cache");
const fs = handle.fs();

const entries = await fs.list("/");
const config = await fs.readToString("/.npmrc");
await fs.write("/audit.txt", new TextEncoder().encode("ok\n"));

VolumeFs exposes read, readToString, readStream, write, writeStream, list, mkdir, remove, removeDir, copy, rename, stat, exists.

ExecOutput

class ExecOutput {
  get code(): number;
  get success(): boolean;            // code === 0
  stdout(): string;                  // decoded UTF-8
  stderr(): string;
  stdoutBytes(): Uint8Array;
  stderrBytes(): Uint8Array;
}

ExecHandle (streaming)

class ExecHandle implements AsyncIterable<ExecEvent> {
  recv(): Promise<ExecEvent | null>;     // pull one event manually
  wait(): Promise<ExitStatus>;           // await final exit code without iterating
  collect(): Promise<ExecOutput>;        // drain to an ExecOutput
  kill(): Promise<void>;
}

type ExecEvent =
  | { kind: "started"; pid: number }
  | { kind: "stdout"; data: Uint8Array }
  | { kind: "stderr"; data: Uint8Array }
  | { kind: "exited"; code: number };