Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Exec

Accessed via sandbox.exec.

sandbox.exec.run(command, opts?)

Run a command synchronously. HTTP API →
body commandstringrequired
Shell command
body timeoutnumberdefault: 60
Timeout in seconds
body envRecord<string, string>
Environment variables
body cwdstring
Working directory
Returns: Promise<ProcessResult>
typescript
const result = await sandbox.exec.run("npm test", { cwd: "/app" });

sandbox.exec.start(command, opts?)

Start a long-running command with streaming. HTTP API →
body commandstringrequired
Command
body argsstring[]
Arguments
body envRecord<string, string>
Environment variables
body cwdstring
Working directory
body timeoutnumber
Timeout in seconds
body maxRunAfterDisconnectnumber
Seconds to keep running after disconnect
body onStdout(data: Uint8Array) => void
Stdout callback
body onStderr(data: Uint8Array) => void
Stderr callback
body onExit(exitCode: number) => void
Exit callback
Returns: Promise<ExecSession>
typescript
const session = await sandbox.exec.start("node server.js", {
  onStdout: (data) => process.stdout.write(data),
});

sandbox.exec.background(command, opts?)

Alias for start. Same options, same return type. Use when the intent is "run this in the background and observe it" — more discoverable than start for that case.
typescript
const server = await sandbox.exec.background("npm", {
  args: ["run", "dev"],
  onStdout: (data) => process.stdout.write(data),
});

sandbox.exec.shell(opts?)

Open a stateful shell session. Subsequent .run() calls share the same bash process, so cwd, exported env vars, and shell functions persist — the ergonomics of a terminal tab.
Backed by a long-running bash --noprofile --norc session. Foreground-only: concurrent .run() rejects with ShellBusyError. Use background for fire-and-forget processes.
body cwdstring
Initial working directory
body envRecord<string, string>
Initial environment variables
Returns: Promise<Shell>
typescript
const sh = await sandbox.exec.shell({ cwd: "/app" });

await sh.run("npm install");
await sh.run("export NODE_ENV=test");
const r = await sh.run("npm test", {
  onStdout: (b) => process.stdout.write(b),
});
console.log(r.exitCode);

await sh.close();

Shell

MemberTypeDescription
sessionIdstringUnderlying exec session ID
run(cmd, opts?)Promise<ProcessResult>Run a command, blocking until it exits
close()Promise<void>Write exit and wait for bash to terminate

ShellRunOpts

ParameterTypeDescription
onStdout(data: Uint8Array) => voidPer-call stdout callback
onStderr(data: Uint8Array) => voidPer-call stderr callback
Per-call cwd, env, and timeout are intentionally not supported in v1. Use inline shell syntax (cd /x && cmd, FOO=bar cmd) — the shell state carries across calls. Timeouts will land once we have a "signal foreground job" primitive.
Errors:
  • ShellBusyError — another run() is in flight (shell is foreground-only).
  • ShellClosedError — bash has exited (explicit close(), a command ran exit, or the session dropped).

sandbox.exec.attach(sessionId, opts?)

Reconnect to a running exec session.
body sessionIdstringrequired
Session ID
body onStdout(data: Uint8Array) => void
Stdout callback
body onStderr(data: Uint8Array) => void
Stderr callback
body onExit(exitCode: number) => void
Exit callback
body onScrollbackEnd() => void
Scrollback replay done
Returns: Promise<ExecSession>

sandbox.exec.list()

List all exec sessions. HTTP API →
Returns: Promise<ExecSessionInfo[]>

sandbox.exec.kill(sessionId, signal?)

Kill an exec session. Default signal: 9 (SIGKILL). HTTP API →
Returns: Promise<void>

ExecSession

MemberTypeDescription
sessionIdstringSession ID
donePromise<number>Resolves with exit code
sendStdin(data)methodSend input (string or Uint8Array)
kill(signal?)Promise<void>Kill process
close()methodClose WebSocket

Types

ProcessResult
typescript
interface ProcessResult {
  exitCode: number;
  stdout: string;
  stderr: string;
}
ExecSessionInfo
typescript
interface ExecSessionInfo {
  sessionID: string;
  sandboxID: string;
  command: string;
  args: string[];
  running: boolean;
  exitCode?: number;
  startedAt: string;
  attachedClients: number;
}