List & connect to sandboxes

Sandbox.list(), Sandbox.get(), and connectToSandbox().

connectToSandbox(name) → Promise<Sandbox>

The most common case: you (or another process) launched a sandbox and detached it. Now you want a live Sandbox handle to drive it.

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

const sb = await connectToSandbox("agent-1");
console.log((await sb.shell("pi --version")).stdout());

This is a thin wrapper around Sandbox.get(name).connect() — a two-step lookup in the underlying SDK.

Sandbox.list() → Promise<SandboxHandle[]>

Enumerate every sandbox the SDK knows about — both running and stopped.

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

for (const h of await Sandbox.list()) {
  console.log(`${h.name} (${h.status})`);
  // h.status: "running" | "stopped" | "crashed" | ...
}

Each entry is a SandboxHandle with metadata only — no live connection. To drive it, call connectToSandbox(h.name) or h.connect() directly. To start a stopped one, call h.start() / h.startDetached().

Sandbox.get(name) → Promise<SandboxHandle>

Look one up by name. Throws if it doesn’t exist. Returns a SandboxHandle — metadata + .connect() / .start() / .remove() methods.

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

const handle = await Sandbox.get("agent-1");
console.log(handle.status);

const sb = await handle.connect();              // open a live channel

Prefer connectToSandbox for the common “give me a live handle by name” case.