Exec

Accessed via sandbox.exec.

`sandbox.exec.run(command, opts?)`

Run a command synchronously. HTTP API →

string

required

Shell command

number

default:"60"

Timeout in seconds

Record<string, string>

Environment variables

string

Working directory

Returns: Promise<ProcessResult>

const result = await sandbox.exec.run("npm test", { cwd: "/app" });

`sandbox.exec.start(command, opts?)`

Start a long-running command with streaming. HTTP API →

string

required

Command

string[]

Arguments

Record<string, string>

Environment variables

string

Working directory

number

Timeout in seconds

number

Seconds to keep running after disconnect

(data: Uint8Array) => void

Stdout callback

(data: Uint8Array) => void

Stderr callback

(exitCode: number) => void

Exit callback

Returns: Promise<ExecSession>

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.

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.

string

Initial working directory

Record<string, string>

Initial environment variables

Returns: Promise<Shell>

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

Member	Type	Description
`sessionId`	`string`	Underlying 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

Parameter	Type	Description
`onStdout`	`(data: Uint8Array) => void`	Per-call stdout callback
`onStderr`	`(data: Uint8Array) => void`	Per-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.

string

required

Session ID

(data: Uint8Array) => void

Stdout callback

(data: Uint8Array) => void

Stderr callback

(exitCode: number) => void

Exit callback

() => 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

Member	Type	Description
`sessionId`	`string`	Session ID
`done`	`Promise<number>`	Resolves with exit code
`sendStdin(data)`	method	Send input (string or Uint8Array)
`kill(signal?)`	`Promise<void>`	Kill process
`close()`	method	Close WebSocket

Types

ProcessResult

interface ProcessResult {
  exitCode: number;
  stdout: string;
  stderr: string;
}

ExecSessionInfo

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

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Self-hosting

`sandbox.exec.run(command, opts?)`

`sandbox.exec.start(command, opts?)`

`sandbox.exec.background(command, opts?)`

`sandbox.exec.shell(opts?)`

Shell

ShellRunOpts

`sandbox.exec.attach(sessionId, opts?)`

`sandbox.exec.list()`

`sandbox.exec.kill(sessionId, signal?)`

ExecSession

Types

​sandbox.exec.run(command, opts?)

​sandbox.exec.start(command, opts?)

​sandbox.exec.background(command, opts?)

​sandbox.exec.shell(opts?)

​Shell

​ShellRunOpts

​sandbox.exec.attach(sessionId, opts?)

​sandbox.exec.list()

​sandbox.exec.kill(sessionId, signal?)

​ExecSession

​Types

`sandbox.exec.run(command, opts?)`

`sandbox.exec.start(command, opts?)`

`sandbox.exec.background(command, opts?)`

`sandbox.exec.shell(opts?)`

Shell

ShellRunOpts

`sandbox.exec.attach(sessionId, opts?)`

`sandbox.exec.list()`

`sandbox.exec.kill(sessionId, signal?)`

ExecSession

Types