Stop & delete sandboxes

sb.stop(), sb.detach(), sb.kill(), and removeSandbox().

On a live handle

Once you have a Sandbox (from launchSandbox or connectToSandbox), the SDK gives you three lifecycle methods:

sb.stop() → Promise<void>

Graceful shutdown — sends SIGTERM, waits briefly, then stops the VM. Use this when you’re done.

await sb.stop();

sb.kill() → Promise<void>

Hard kill — SIGKILL, no grace period. Use when stop() is hanging because something inside the guest is holding a tty or a non-interruptible syscall.

sb.detach() → Promise<void>

Sever the lifecycle binding. After this returns, the VM keeps running even after your process exits. The Sandbox object becomes unusable (any further method calls throw “handle consumed”) — to drive the VM later, look it up via connectToSandbox(name).

await sb.detach();
// sandbox keeps running...

removeSandbox(name, opts?) → Promise<void>

Delete a sandbox from the local DB so the name is reusable. Idempotent — silently succeeds if it doesn’t exist.

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

await removeSandbox("agent-1");                       // remove if stopped
await removeSandbox("agent-1", { force: true });      // kill first if still running

Options

Stopping without a live handle

If you only know the sandbox by name:

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

const handle = await Sandbox.get("agent-1");
await handle.stop();        // or .kill() / .remove()

Or compose:

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

const sb = await connectToSandbox("agent-1");
await sb.stop();