Skip to content
View as Markdown

ProcessHandle

Section titled “ProcessHandle”

Properties:

  • id string
  • sandboxId string
  • kind? ProcessKind

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
new ProcessHandle(
   transport: HttpTransport,
   sandboxId: string,
   processId: string,
   kind?: ProcessKind): ProcessHandle;

Parameters:

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

Returns:

  • ProcessHandle

Methods

Section titled “Methods”

attach()

Section titled “attach()”
attach(): Promise<PtyDuplex>;

Returns:

  • Promise<PtyDuplex>

delete()

Section titled “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()

Section titled “get()”
get(): Promise<ProcessDto>;

Returns:

  • Promise<ProcessDto>

kill()

Section titled “kill()”
kill(options: KillOptions = {}): Promise<void>;

Parameters:

  • options KillOptions = {}

Returns:

  • Promise<void>

logs()

Section titled “logs()”
logs(options: LogsOptions = {}): Promise<LogsPage>;

Parameters:

  • options LogsOptions = {}

Returns:

  • Promise<LogsPage>

resize()

Section titled “resize()”
resize(cols: number, rows: number): Promise<void>;

Parameters:

  • cols number
  • rows number

Returns:

  • Promise<void>

stdin()

Section titled “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()

Section titled “stdinEof()”
stdinEof(): Promise<void>;

Close stdin for an exec or pty process.

Returns:

  • Promise<void>

streamLogs()

Section titled “streamLogs()”
streamLogs(options: StreamLogsOptions = {}): AsyncIterable<StreamLogEvent>;

Parameters:

  • options StreamLogsOptions = {}

Returns:

  • AsyncIterable<StreamLogEvent>

toJSON()

Section titled “toJSON()”
toJSON(): ProcessHandleJSON;

Returns:

  • ProcessHandleJSON

wait()

Section titled “wait()”
wait(options: WaitProcessOptions = {}): Promise<WaitResult>;

Parameters:

  • options WaitProcessOptions = {}

Returns:

  • Promise<WaitResult>

ProcessService

Section titled “ProcessService”

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
new ProcessService(transport: HttpTransport, sandboxId: string): ProcessService;

Parameters:

  • transport HttpTransport
  • sandboxId string

Returns:

  • ProcessService

Methods

Section titled “Methods”

connect()

Section titled “connect()”
connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • ProcessHandle

connectSession()

Section titled “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()

Section titled “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()

Section titled “get()”
get(id: string): Promise<ProcessDto>;

Parameters:

  • id string

Returns:

  • Promise<ProcessDto>

list()

Section titled “list()”
list(options: ProcessListOptions = {}): Promise<ListResult<ProcessDto>>;

Parameters:

  • options ProcessListOptions = {}

Returns:

  • Promise<ListResult<ProcessDto>>

run()

Section titled “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()

Section titled “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

Section titled “PtyService”

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
new PtyService(process: ProcessService): PtyService;

Parameters:

  • process ProcessService

Returns:

  • PtyService

Methods

Section titled “Methods”

attach()

Section titled “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()

Section titled “connect()”
connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • ProcessHandle

delete()

Section titled “delete()”
delete(idOrHandle: string | ProcessHandleJSON): Promise<void>;

Parameters:

  • idOrHandle string | ProcessHandleJSON

Returns:

  • Promise<void>

list()

Section titled “list()”
list(): Promise<ListResult<ProcessDto>>;

Returns:

  • Promise<ListResult<ProcessDto>>

start()

Section titled “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

Section titled “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

Section titled “Constructors”

Constructor

Section titled “Constructor”
new Session(binding: ProcessBinding, id: string): Session;

Parameters:

  • binding ProcessBinding
  • id string

Returns:

  • Session

Methods

Section titled “Methods”

[Symbol.asyncDispose]()

Section titled “[Symbol.asyncDispose]()”
[Symbol.asyncDispose](): Promise<void>;

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

Returns:

  • Promise<void>

delete()

Section titled “delete()”
delete(): Promise<void>;

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

Returns:

  • Promise<void>

get()

Section titled “get()”
get(): Promise<ProcessDto>;

Read the shell process, including its current working directory.

Returns:

  • Promise<ProcessDto>

run()

Section titled “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()

Section titled “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()

Section titled “toJSON()”
toJSON(): SessionJSON;

Returns:

  • SessionJSON

PtyDuplex

Section titled “PtyDuplex”

Properties:

  • readable AsyncIterable<Uint8Array>

Methods

Section titled “Methods”

close()

Section titled “close()”
close(): void;

Returns:

  • void

write()

Section titled “write()”
write(data: string | Uint8Array): void;

Parameters:

  • data string | Uint8Array

Returns:

  • void

CreateSessionOptions

Section titled “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

Section titled “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

Section titled “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

Section titled “SessionJSON”

Properties:

  • sandboxId string
  • sessionId string

ProcessHandleJSON

Section titled “ProcessHandleJSON”

Properties:

  • sandboxId string
  • processId string
  • kind? ProcessKind

ProcessKind

Section titled “ProcessKind”
type ProcessKind = 'exec' | 'pty' | 'code' | 'session'

ProcessReportedKind

Section titled “ProcessReportedKind”
type ProcessReportedKind = ProcessKind | 'unknown'

ProcessState

Section titled “ProcessState”
type ProcessState = 'starting' | 'provisioning' | 'running' | 'terminal' | 'unknown'

ProcessSignal

Section titled “ProcessSignal”
type ProcessSignal = 'TERM' | 'KILL' | 'INT' | 'HUP' | 'QUIT' | 'USR1' | 'USR2'

ProcessReason

Section titled “ProcessReason”
type ProcessReason = 'exited' | 'signaled' | 'timed_out' | 'lost' | 'failed' | 'unknown'

KeepLogs

Section titled “KeepLogs”
type KeepLogs = 'until_cleanup' | 'on_exit_ttl' | 'none'

ProcessKeepLogs

Section titled “ProcessKeepLogs”
type ProcessKeepLogs = KeepLogs | 'unknown'

ProcessStdinMode

Section titled “ProcessStdinMode”
type ProcessStdinMode = 'closed' | 'open' | 'unknown'

TerminalSize

Section titled “TerminalSize”
type TerminalSize = toolbox.TerminalSize

ProcessDto

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

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

LogFrame

Section titled “LogFrame”

Properties:

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

LogsPage

Section titled “LogsPage”

Extends: ListResult<LogFrame>

Properties:

  • truncatedHead? boolean
  • firstAvailableCursor? string

StreamLogEvent

Section titled “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

Section titled “LogsOptions”

Properties:

  • cursor? string
  • limit? number
  • encoding? ‘text’ | ‘base64’

StreamLogsOptions

Section titled “StreamLogsOptions”

Properties:

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

KillOptions

Section titled “KillOptions”

Properties:

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

ProcessListOptions

Section titled “ProcessListOptions”

Properties:

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