Sign Up

ProcessHandle

Properties:

  • id string
  • sandboxId string
  • kind? ProcessKind

Constructors

Constructor

new ProcessHandle(
   transport: HttpTransport,
   sandboxId: string,
   processId: string,
   kind?: ProcessKind): ProcessHandle;

Parameters:

  • transport HttpTransport
  • sandboxId string
  • processId string
  • kind? ProcessKind

Returns:

  • ProcessHandle

Methods

attach()

attach(): Promise<PtyDuplex>;

Returns:

  • Promise<PtyDuplex>

delete()

delete(): Promise<void>;

Delete the process and its logs, stopping it first if it is running. Refused (UnsupportedOperationError) for a running code cell, and for a session command that has not stopped within 5 s: delete its session.

Returns:

  • Promise<void>

get()

get(): Promise<ProcessDto>;

Returns:

  • Promise<ProcessDto>

kill()

kill(options: KillOptions = {}): Promise<void>;

Parameters:

  • options KillOptions = {}

Returns:

  • Promise<void>

logs()

logs(options: LogsOptions = {}): Promise<LogsPage>;

Parameters:

  • options LogsOptions = {}

Returns:

  • Promise<LogsPage>

resize()

resize(cols: number, rows: number): Promise<void>;

Parameters:

  • cols number
  • rows number

Returns:

  • Promise<void>

stdin()

stdin(data: string | Uint8Array, options: { eof?: boolean } = {}): Promise<void>;

Write stdin to an exec or pty process created with stdin='open'.

Parameters:

  • data string | Uint8Array
  • options { eof?: boolean } = {}

Returns:

  • Promise<void>

stdinEof()

stdinEof(): Promise<void>;

Close stdin for an exec or pty process.

Returns:

  • Promise<void>

streamLogs()

streamLogs(options: StreamLogsOptions = {}): AsyncIterable<StreamLogEvent>;

Parameters:

  • options StreamLogsOptions = {}

Returns:

  • AsyncIterable<StreamLogEvent>

toJSON()

toJSON(): ProcessHandleJSON;

Returns:

  • ProcessHandleJSON

wait()

wait(options: WaitProcessOptions = {}): Promise<WaitResult>;

Parameters:

  • options WaitProcessOptions = {}

Returns:

  • Promise<WaitResult>

ProcessService

Constructors

Constructor

new ProcessService(transport: HttpTransport, sandboxId: string): ProcessService;

Parameters:

  • transport HttpTransport
  • sandboxId string

Returns:

  • ProcessService

Methods

connect()

connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • ProcessHandle

connectSession()

connectSession(sessionIdOrJSON: string | SessionJSON): Session;

Rebind a shell session by id or serialized identity, without a request.

Parameters:

  • sessionIdOrJSON string | SessionJSON

Returns:

  • Session

createSession()

createSession(options: CreateSessionOptions = {}): Promise<Session>;

Create one persistent shell. Set its cwd/env here, not on its commands.

Parameters:

  • options CreateSessionOptions = {}

Returns:

  • Promise<Session>

get()

get(id: string): Promise<ProcessDto>;

Parameters:

  • id string

Returns:

  • Promise<ProcessDto>

list()

list(options: ProcessListOptions = {}): Promise<ListResult<ProcessDto>>;

Parameters:

  • options ProcessListOptions = {}

Returns:

  • Promise<ListResult<ProcessDto>>

run()

run(command: ProcessCommand, options: RunOptions = {}): Promise<RunResult>;

Run a command, wait for its shell to exit, and collect its output.

Normally one round trip: starts, waits, and returns inline logs. Larger output or a process outliving the wait window falls back to split calls. Output is bounded by per-process retention; a timed-out result collects only the first few log pages rather than chasing a live writer.

Strings (or { cmd }) use the sandbox shell (bash, else sh; override with shell). Quote globs and brackets (pip install -e '.[test]'). { argv: [...] } bypasses the shell for untrusted arguments. For shared shell state, use createSession instead.

Background children holding output descriptors open drain for at most about two seconds after the shell exits; later output is not included. Prefer start for long-running servers, or redirect their output (nohup cmd > server.log 2>&1 &).

Parameters:

  • command ProcessCommand - Shell command string, { cmd }, or shell-free { argv }.
  • options RunOptions = {}

Returns:

  • Promise<RunResult> - Output, stdout, stderr, logs and the exit result.

start()

start(
   command: ProcessCommand,
   options: ProcessStartOptions = {}): Promise<ProcessHandle>;

Start a detached process and return a handle immediately.

Use ProcessHandle.streamLogs, ProcessHandle.wait, or ProcessHandle.kill to control it. Prefer this for long-running servers: start once, then poll the port or stream logs for readiness.

String commands (or { cmd }) run through the sandbox shell (bash, else sh; pin another with shell). Quote globs and brackets, such as pip install -e '.[test]'. Pass { argv: [...] } to bypass the shell for untrusted arguments. Plain commands do not share shell state; use createSession for a persistent shell.

Parameters:

  • command ProcessCommand - Shell command string, { cmd }, or shell-free { argv }.
  • options ProcessStartOptions = {}

Returns:

  • Promise<ProcessHandle>

PtyService

Constructors

Constructor

new PtyService(process: ProcessService): PtyService;

Parameters:

  • process ProcessService

Returns:

  • PtyService

Methods

attach()

attach(
   command?: string,
   options: Omit<ProcessStartOptions, 'cmd'> & { terminal?: TerminalSize } = {}): Promise<{ handle: ProcessHandle; connection: PtyDuplex }>;

Parameters:

  • command? string
  • options Omit<ProcessStartOptions, 'cmd'> & { terminal?: TerminalSize } = {}

Returns:

  • Promise<{ handle: ProcessHandle; connection: PtyDuplex }>

connect()

connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • ProcessHandle

delete()

delete(idOrHandle: string | ProcessHandleJSON): Promise<void>;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • Promise<void>

list()

list(): Promise<ListResult<ProcessDto>>;

Returns:

  • Promise<ListResult<ProcessDto>>

start()

start(
   command?: string,
   options: Omit<ProcessStartOptions, 'cmd'> & { terminal?: TerminalSize } = {}): Promise<ProcessHandle>;

Parameters:

  • command? string
  • options Omit<ProcessStartOptions, 'cmd'> & { terminal?: TerminalSize } = {}

Returns:

  • Promise<ProcessHandle>

Session

One persistent shell. Commands run one at a time, in order; cd, exports, and functions carry over. Set cwd/env with process.createSession(). Interrupt a command with handle.kill({ signal: 'INT' }): the session survives. Sessions survive pause/resume, but not a sandbox stop/start. On Windows, interrupts and executionTimeout stop external programs but cannot interrupt PowerShell loops or cmdlets, and commands cannot take stdin: 'open'. After set -x or set -v in a session, later commands' stderr also traces the daemon's own lines that run each command.

Properties:

  • sandboxId string
  • id string

Constructors

Constructor

new Session(binding: ProcessBinding, id: string): Session;

Parameters:

  • binding ProcessBinding
  • id string

Returns:

  • Session

Methods

[Symbol.asyncDispose]()

[Symbol.asyncDispose](): Promise<void>;

Deletes the session on scope exit; one already deleted in the scope is fine.

Returns:

  • Promise<void>

delete()

delete(): Promise<void>;

End the shell and delete it and all its command records.

Returns:

  • Promise<void>

get()

get(): Promise<ProcessDto>;

Read the shell process, including its current working directory.

Returns:

  • Promise<ProcessDto>

run()

run(command: string, options: SessionRunOptions = {}): Promise<RunResult>;

Run in this shell, wait, and collect output using the process run path.

Parameters:

  • command string
  • options SessionRunOptions = {}

Returns:

  • Promise<RunResult>

start()

start(command: string, options: SessionStartOptions = {}): Promise<ProcessHandle>;

Queue a command and return its handle without waiting for completion.

Parameters:

  • command string
  • options SessionStartOptions = {}

Returns:

  • Promise<ProcessHandle>

toJSON()

toJSON(): SessionJSON;

Returns:

  • SessionJSON

PtyDuplex

Properties:

  • readable AsyncIterable<Uint8Array>

Methods

close()

close(): void;

Returns:

  • void

write()

write(data: string | Uint8Array): void;

Parameters:

  • data string | Uint8Array

Returns:

  • void

CreateSessionOptions

Settings for the persistent shell, inherited by every command.

Properties:

  • cwd? string
  • env? Readonly<Record<string, string>>
  • shell? string - A POSIX shell (bash, sh, dash, zsh, ksh) on Linux and macOS; another shell is refused when the session is created. On Windows, pwsh or powershell.
  • login? boolean
  • name? string

SessionRunOptions

Properties:

  • stdin? 'closed' | 'open'
  • executionTimeout? number - Server-side command deadline in milliseconds. The clock starts when the command starts, after any queued commands ahead of it. The command is stopped and the session survives; a command that has not stopped 5 s after its timeout ends the session instead of blocking it. In dash, BusyBox sh and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS's /bin/bash) when a DEBUG trap is set.
  • name? string
  • keepLogs? KeepLogs
  • timeout? number - Caller wait budget in milliseconds; omitted or 0 waits unbounded.

SessionStartOptions

Properties:

  • stdin? 'closed' | 'open'
  • executionTimeout? number - Server-side command deadline in milliseconds. The clock starts when the command starts, after any queued commands ahead of it. The command is stopped and the session survives; a command that has not stopped 5 s after its timeout ends the session instead of blocking it. In dash, BusyBox sh and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS's /bin/bash) when a DEBUG trap is set.
  • name? string
  • keepLogs? KeepLogs

SessionJSON

Properties:

  • sandboxId string
  • sessionId string

ProcessHandleJSON

Properties:

  • sandboxId string
  • processId string
  • kind? ProcessKind

ProcessKind

type ProcessKind = 'exec' | 'pty' | 'code' | 'session'

ProcessReportedKind

type ProcessReportedKind = ProcessKind | 'unknown'

ProcessState

type ProcessState = 'starting' | 'provisioning' | 'running' | 'terminal' | 'unknown'

ProcessSignal

type ProcessSignal = 'TERM' | 'KILL' | 'INT' | 'HUP' | 'QUIT' | 'USR1' | 'USR2'

ProcessReason

type ProcessReason = 'exited' | 'signaled' | 'timed_out' | 'lost' | 'failed' | 'unknown'

KeepLogs

type KeepLogs = 'until_cleanup' | 'on_exit_ttl' | 'none'

ProcessKeepLogs

type ProcessKeepLogs = KeepLogs | 'unknown'

ProcessStdinMode

type ProcessStdinMode = 'closed' | 'open' | 'unknown'

TerminalSize

type TerminalSize = toolbox.TerminalSize

ProcessDto

Properties:

  • id string
  • name? string
  • pid? number
  • kind ProcessReportedKind
  • rawKind string
  • state ProcessState
  • rawState string
  • system boolean
  • sessionId? string
  • argv? string[]
  • shellCommand? string
  • code? string
  • language? string
  • shell? string
  • resolvedShell? string
  • login? boolean
  • cwd? string
  • user? string
  • stdin? ProcessStdinMode
  • rawStdin? string
  • executionTimeout? number - Server-managed process deadline in milliseconds.
  • terminal? TerminalSize
  • keepLogs? ProcessKeepLogs
  • rawKeepLogs? string
  • exitCode? number
  • signal? string
  • reason? ProcessReason
  • rawReason? string
  • createdAt? string
  • startedAt? string
  • exitedAt? string
  • truncatedHead? boolean
  • firstAvailableCursor? string
  • lastCursor? string

WaitResult

type WaitResult =
  | { reason: 'exited'; exitCode: number; signal?: undefined; rawReason?: string }
  | { reason: 'signaled'; signal: string; exitCode?: undefined; rawReason?: string }
  | { reason: 'timed_out'; exitCode?: undefined; signal?: undefined; rawReason?: string }
  | { reason: 'lost' | 'failed'; exitCode?: number; signal?: string; rawReason?: string }
  | { reason: 'unknown'; exitCode?: number; signal?: string; rawReason: string }

ProcessStartOptions

Properties:

  • cmd? string
  • argv? string[]
  • name? string
  • cwd? string
  • env? Record<string, string>
  • user? string
  • shell? string
  • login? boolean
  • stdin? 'closed' | 'open'
  • executionTimeout? number - Server-managed process deadline in milliseconds.
  • terminal? TerminalSize
  • keepLogs? KeepLogs

ProcessCommand

type ProcessCommand = string | { cmd: string; argv?: never } | { argv: readonly string[]; cmd?: never }

What to execute, as the first argument of process.start() / process.run() / sandbox.exec(): a shell command string, or an object naming exactly one of cmd (shell) or argv (exec, no shell — the safe form for untrusted arguments). Mirrors Python's command= / argv= keywords.

RunOptions

type RunOptions = Omit<ProcessStartOptions, 'kind'> & {
  /** Caller wait budget in milliseconds; `0` waits unbounded. */
  timeout?: number
  /** `run()` only creates exec processes; PTYs come from `sandbox.pty.start()` / `attach()`. */
  kind?: 'exec'
}

RunResult

type RunResult = WaitResult & {
  processId: string
  output: string
  stdout: string
  stderr: string
  logs: LogFrame[]
}

LogFrame

Properties:

  • cursor string
  • channel 'stdout' | 'stderr' | 'pty' | 'setup' | string
  • data string
  • encoding? 'text' | 'base64' | string
  • timestamp? number

LogsPage

Extends: ListResult<LogFrame>

Properties:

  • truncatedHead? boolean
  • firstAvailableCursor? string

StreamLogEvent

type StreamLogEvent =
  | { type: 'log'; cursor?: string; frame: LogFrame }
  | { type: 'state'; cursor?: string; result: WaitResult }
  | { type: 'warning'; cursor?: string; message: string; firstAvailableCursor?: string }
  | { type: 'eof'; cursor?: string }
  | { type: 'error'; cursor?: string; error: Error }

LogsOptions

Properties:

  • cursor? string
  • limit? number
  • encoding? 'text' | 'base64'

StreamLogsOptions

Properties:

  • cursor? string
  • limit? number
  • encoding? 'text' | 'base64'
  • signal? AbortSignal

KillOptions

Properties:

  • signal? ProcessSignal
  • escalateAfter? number
  • escalateTo? ProcessSignal

ProcessListOptions

Properties:

  • state? 'running' | 'terminal' | 'all'
  • kind? ProcessKind
  • sessionId? string
  • name? string
  • pid? number

On this page

ProcessHandleConstructorsConstructorMethodsattach()delete()get()kill()logs()resize()stdin()stdinEof()streamLogs()toJSON()wait()ProcessServiceConstructorsConstructorMethodsconnect()connectSession()createSession()get()list()run()start()PtyServiceConstructorsConstructorMethodsattach()connect()delete()list()start()SessionConstructorsConstructorMethods[Symbol.asyncDispose]()delete()get()run()start()toJSON()PtyDuplexMethodsclose()write()CreateSessionOptionsSessionRunOptionsSessionStartOptionsSessionJSONProcessHandleJSONProcessKindProcessReportedKindProcessStateProcessSignalProcessReasonKeepLogsProcessKeepLogsProcessStdinModeTerminalSizeProcessDtoWaitResultProcessStartOptionsProcessCommandRunOptionsRunResultLogFrameLogsPageStreamLogEventLogsOptionsStreamLogsOptionsKillOptionsProcessListOptions

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free