Sign Up
Docs v2.0

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>

cleanup()

cleanup(): Promise<void>;

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

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.

The common case is one round trip: the daemon starts the process, parks the request until it exits (or timeout expires), and returns the output inline. A process that outlives the wait window or produces more output than fits in one page falls back to split calls automatically.

The result holds the output the daemon still has when the call returns: its per-process log is bounded, so very large output loses its oldest frames, and a result that timed out collects only the first few log pages.

Shell selection. A string command (or { cmd }) runs through the sandbox shell (bash, else sh; pin another with shell). Quote globs and brackets (pip install -e '.[test]') so the command means the same under any shell. Pass { argv: [...] } to bypass the shell entirely, which is the safe form for untrusted arguments. With sessionId the command runs in that session's shell instead, where argv and executionTimeout do not apply.

Background processes. The call returns when the shell exits. If the command forks a background child that holds its output descriptors open (e.g. python3 -m http.server 8000 &), the daemon waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server prefer start, which returns a ProcessHandle immediately, or redirect: nohup cmd > server.log 2>&1 &.

Parameters:

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

Returns:

  • Promise<RunResult>

Example:

const result = await sandbox.process.run('pip install httpx')
if (result.exitCode !== 0) throw new Error(result.stderr)

start()

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

Start a detached process and return a handle immediately.

Unlike run, this returns as soon as the daemon has started the process. Use the returned ProcessHandle to stream logs (handle.streamLogs()), wait for exit (handle.wait()), or kill (handle.kill()). This is the right choice for long-running servers — call start() once, then poll the port or stream logs to confirm the server is ready.

Shell selection. A string command (or { cmd }) runs through the sandbox shell (bash, else sh; pin another with shell). Quote globs and brackets (pip install -e '.[test]'). Pass { argv: [...] } to bypass the shell for untrusted input. With sessionId the command runs in that session's shell instead, where argv and executionTimeout do not apply.

Parameters:

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

Returns:

  • Promise<ProcessHandle> - Bound ProcessHandle — logs, wait, and kill are available immediately.

Example:

const handle = await sandbox.process.start('python3 -m http.server 8000')
// poll or stream logs; the process keeps running in the background

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>

PtyDuplex

Properties:

  • readable AsyncIterable<Uint8Array>

Methods

close()

close(): void;

Returns:

  • void

write()

write(data: string | Uint8Array): void;

Parameters:

  • data string | Uint8Array

Returns:

  • void

ProcessHandleJSON

Properties:

  • sandboxId string
  • processId string
  • kind? ProcessKind

ProcessKind

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

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'

ProcessKeepLogs

type ProcessKeepLogs = KeepLogs | 'unknown'

ProcessStdinMode

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

TerminalSize

type TerminalSize = OptionalizeNullable<Schema<"TerminalSize">>

ProcessDto

type ProcessDto = Simplify<ProcessRecord & {
  firstAvailableCursor?: string
  lastCursor?: string
  truncatedHead: boolean
  system: boolean
  /** Only on a `POST /processes?waitMs=…&logs=` response. */
  logs?: ProcessLogsResponse
}>

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
  • sessionId? 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

KeepLogs

const KeepLogs = ["until_cleanup","on_exit_ttl","none"] as const

On this page

ProcessHandleConstructorsConstructorMethodsattach()cleanup()get()kill()logs()resize()stdin()stdinEof()streamLogs()toJSON()wait()ProcessServiceConstructorsConstructorMethodsconnect()get()list()run()start()PtyServiceConstructorsConstructorMethodsattach()connect()delete()list()start()PtyDuplexMethodsclose()write()ProcessHandleJSONProcessKindProcessReportedKindProcessStateProcessSignalProcessReasonProcessKeepLogsProcessStdinModeTerminalSizeProcessDtoWaitResultProcessStartOptionsProcessCommandRunOptionsRunResultLogFrameLogsPageStreamLogEventLogsOptionsStreamLogsOptionsKillOptionsProcessListOptionsKeepLogs

Computersfor Agents

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

Start for Free