Commands

CommandInputHandle

An ordered, long-lived input handle for a command or PTY.

Methods

close()

close(): Promise<void>

Finish the input stream and wait for envd to acknowledge it.

Returns

Promise<void> A promise that resolves when envd acknowledges the end of the input stream.

Throws

If the command or PTY does not exist.

Throws

If the input stream times out.

send()

send(data: string | Uint8Array<ArrayBufferLike>): Promise<void>

Enqueue input for transmission in call order.

Parameters

Parameter	Type	Description
`data`	`string` \| `Uint8Array`<`ArrayBufferLike`>	Input data to send.

Returns

Promise<void> A promise that resolves when the input is queued for ordered transmission.

Throws

If the command or PTY does not exist.

Throws

If the input stream times out.

Throws

If this handle is closed.

Module for starting and interacting with commands in the sandbox.

Constructors

new Commands(
   transport: Transport, 
   envdApi: EnvdApiClient, 
   connectionConfig: ConnectionConfig, 
   streamingTransport: Transport): Commands

Parameters

Parameter	Type
`transport`	`Transport`
`envdApi`	`EnvdApiClient`
`connectionConfig`	`ConnectionConfig`
`streamingTransport`	`Transport`

Returns

Commands

Methods

closeStdin()

closeStdin(pid: number, opts?: CommandRequestOpts): Promise<void>

Close command stdin. This signals EOF to the command. The command must have been started with stdin: true.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the command. You can get the list of running commands using Commands.list.
`opts`?	`CommandRequestOpts`	connection options.

Returns

Promise<void>

connect()

connect(pid: number, opts?: CommandConnectOpts): Promise<CommandHandle>

Connect to a running command. You can use CommandHandle.wait to wait for the command to finish and get execution results.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the command to connect to. You can get the list of running commands using Commands.list.
`opts`?	`CommandConnectOpts`	connection options.

Returns

Promise<CommandHandle> CommandHandle handle to interact with the running command.

kill()

kill(pid: number, opts?: CommandRequestOpts): Promise<boolean>

Kill a running command specified by its process ID. It uses SIGKILL signal to kill the command.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the command. You can get the list of running commands using Commands.list.
`opts`?	`CommandRequestOpts`	connection options.

Returns

Promise<boolean> true if the command was killed, false if the command was not found.

list()

list(opts?: CommandRequestOpts): Promise<ProcessInfo[]>

List all running commands and PTY sessions.

Parameters

Parameter	Type	Description
`opts`?	`CommandRequestOpts`	connection options.

Returns

Promise<ProcessInfo[]> list of running commands and PTY sessions.

run()

Call Signature

run(cmd: string, opts?: CommandStartOpts & object): Promise<CommandResult>

Start a new command and wait until it finishes executing.

Parameters

Parameter	Type	Description
`cmd`	`string`	command to execute.
`opts`?	`CommandStartOpts` & `object`	options for starting the command.

Returns

Promise<CommandResult> CommandResult result of the command execution.

Call Signature

run(cmd: string, opts: CommandStartOpts & object): Promise<CommandHandle>

Start a new command in the background. You can use CommandHandle.wait to wait for the command to finish and get its result.

Parameters

Parameter	Type	Description
`cmd`	`string`	command to execute.
`opts`	`CommandStartOpts` & `object`	options for starting the command

Returns

Promise<CommandHandle> CommandHandle handle to interact with the running command.

Call Signature

run(cmd: string, opts?: CommandStartOpts & object): Promise<CommandResult | CommandHandle>

Start a new command.

Parameters

Parameter	Type	Description
`cmd`	`string`	command to execute.
`opts`?	`CommandStartOpts` & `object`	options for starting the command. - `opts.background: true` - runs in background, returns `CommandHandle` - `opts.background: false	undefined`- waits for completion, returns`CommandResult`

Returns

Promise<CommandResult | CommandHandle> Either a CommandHandle or a CommandResult (depending on opts.background).

sendStdin()

sendStdin(
   pid: number, 
   data: string | Uint8Array<ArrayBufferLike>, 
opts?: CommandRequestOpts): Promise<void>

Send data to command stdin.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the command. You can get the list of running commands using Commands.list.
`data`	`string` \| `Uint8Array`<`ArrayBufferLike`>	data to send to the command.
`opts`?	`CommandRequestOpts`	connection options.

Returns

Promise<void>

streamInput()

streamInput(pid: number, opts: CommandStreamInputOpts): CommandInputHandle

Open a persistent input stream to a command. Input sent through this stream is ordered relative to other send calls. Use this instead of Commands.sendStdin when ordering matters; each sendStdin call is a separate request. The stream sends keepalive messages while idle. In browsers, this requires fetch request-body streaming support (Chromium over HTTP/2).

Parameters

Parameter	Type	Description
`pid`	`number`	Process ID of the command.
`opts`	`CommandStreamInputOpts`	Optional stream timeout and abort signal. `timeoutMs` defaults to `STREAM_INPUT_TIMEOUT_MS` (60_000 milliseconds).

Returns

CommandInputHandle A handle whose send() method queues input in order and whose close() method ends the stream and waits for envd.

Throws

If the command does not exist, surfaced from send() or close().

Throws

If the stream timeout expires, surfaced from send() or close().

Example

const input = sandbox.commands.streamInput(pid)
await input.send('hello\n')
await input.close()

Pty

Module for interacting with PTYs (pseudo-terminals) in the sandbox.

Constructors

new Pty(
   transport: Transport, 
   envdApi: EnvdApiClient, 
   connectionConfig: ConnectionConfig, 
   streamingTransport: Transport): Pty

Parameters

Parameter	Type
`transport`	`Transport`
`envdApi`	`EnvdApiClient`
`connectionConfig`	`ConnectionConfig`
`streamingTransport`	`Transport`

Returns

Pty

Methods

connect()

connect(pid: number, opts?: PtyConnectOpts): Promise<CommandHandle>

Connect to a running PTY.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the PTY to connect to. You can get the list of running PTYs using Commands.list.
`opts`?	`PtyConnectOpts`	connection options.

Returns

Promise<CommandHandle> handle to interact with the PTY.

create()

create(opts: PtyCreateOpts): Promise<CommandHandle>

Create a new PTY (pseudo-terminal).

Parameters

Parameter	Type	Description
`opts`	`PtyCreateOpts`	options for creating the PTY.

Returns

Promise<CommandHandle> handle to interact with the PTY.

kill()

kill(pid: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>

Kill a running PTY specified by process ID. It uses SIGKILL signal to kill the PTY.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the PTY.
`opts`?	`Pick`<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`>	connection options.

Returns

Promise<boolean> true if the PTY was killed, false if the PTY was not found.

resize()

resize(
   pid: number, 
   size: object, 
opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>

Resize PTY. Call this when the terminal window is resized and the number of columns and rows has changed.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the PTY.
`size`	{ `cols`: `number`; `rows`: `number`; }	new size of the PTY.
`size.cols`	`number`	-
`size.rows`?	`number`	-
`opts`?	`Pick`<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`>	connection options.

Returns

Promise<void>

sendInput()

sendInput(
   pid: number, 
   data: Uint8Array, 
opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>

Send input to a PTY.

Parameters

Parameter	Type	Description
`pid`	`number`	process ID of the PTY.
`data`	`Uint8Array`	input data to send to the PTY.
`opts`?	`Pick`<`ConnectionOpts`, `"requestTimeoutMs"` \| `"signal"`>	connection options.

Returns

Promise<void>

streamInput()

streamInput(pid: number, opts: CommandStreamInputOpts): CommandInputHandle

Open a persistent input stream to a PTY. Input sent through this stream is ordered relative to other send calls. Use this instead of Pty.sendInput when ordering matters; each sendInput call is a separate request. The stream sends keepalive messages while idle. In browsers, this requires fetch request-body streaming support (Chromium over HTTP/2).

Parameters

Parameter	Type	Description
`pid`	`number`	Process ID of the PTY.
`opts`	`CommandStreamInputOpts`	Optional stream timeout and abort signal. `timeoutMs` defaults to `STREAM_INPUT_TIMEOUT_MS` (60_000 milliseconds).

Returns

CommandInputHandle A handle whose send() method queues input in order and whose close() method ends the stream and waits for envd.

Throws

If the PTY does not exist, surfaced from send() or close().

Throws

If the stream timeout expires, surfaced from send() or close().

Example

const input = sandbox.pty.streamInput(pid)
await input.send('echo hello\n')
await input.close()

Interfaces

CommandRequestOpts

Options for sending a command request.

Extended by

CommandStartOpts

Properties

requestTimeoutMs?

optional requestTimeoutMs: number;

Timeout for requests to the API in milliseconds.

Default

60_000 // 60 seconds

signal?

optional signal: AbortSignal;

An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

CommandStartOpts

Options for starting a new command.

Properties

background?

optional background: boolean;

If true, starts command in the background and the method returns immediately. You can use CommandHandle.wait to wait for the command to finish.

cwd?

optional cwd: string;

Working directory for the command.

Default

// home directory of the user used to start the command

envs?

optional envs: Record<string, string>;

Environment variables used for the command. This overrides the default environment variables from Sandbox constructor.

Default

{}

onStderr()?

optional onStderr: (data: string) => void | Promise<void>;

Callback for command stderr output.

Parameters

Parameter	Type
`data`	`string`

Returns

void | Promise<void>

onStdout()?

optional onStdout: (data: string) => void | Promise<void>;

Callback for command stdout output.

Parameters

Parameter	Type
`data`	`string`

Returns

void | Promise<void>

requestTimeoutMs?

optional requestTimeoutMs: number;

Timeout for requests to the API in milliseconds.

Default

60_000 // 60 seconds

signal?

optional signal: AbortSignal;

An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

stdin?

optional stdin: boolean;

If true, command stdin is kept open and you can send data to it using Commands.sendStdin or CommandHandle.sendStdin.

Default

false

timeoutMs?

optional timeoutMs: number;

Timeout for the command in milliseconds.

Default

60_000 // 60 seconds

user?

optional user: string;

User to run the command as.

Default

default Sandbox user (as specified in the template)

CommandStreamInputOpts

Options for streaming input to a command or PTY.

Properties

signal?

optional signal: AbortSignal;

Abort signal for the input stream.

timeoutMs?

optional timeoutMs: number;

Maximum duration of the input stream in milliseconds. 0 disables the timeout.

Default

STREAM_INPUT_TIMEOUT_MS (60_000 milliseconds)

ProcessInfo

Information about a command, PTY session or start command running in the sandbox as process.

Properties

args

args: string[];

Command arguments.

cmd

cmd: string;

Command that was executed.

cwd?

optional cwd: string;

Executed command working directory.

envs

envs: Record<string, string>;

Environment variables used for the command.

pid

pid: number;

Process ID.

tag?

optional tag: string;

Custom tag used for identifying special commands like start command in the custom template.

Type Aliases

CommandConnectOpts

type CommandConnectOpts = Pick<CommandStartOpts, "onStderr" | "onStdout" | "timeoutMs"> & CommandRequestOpts;

Options for connecting to a command.

​CommandInputHandle

​Methods

​close()

Returns

Throws

Throws

​send()

Parameters

Returns

Throws

Throws

Throws

​Commands

​Constructors

Parameters

Returns

​Methods

​closeStdin()

Parameters

Returns

​connect()

Parameters

Returns

​kill()

Parameters

Returns

​list()

Parameters

Returns

​run()

Call Signature

Parameters

Returns

Call Signature

Parameters

Returns

Call Signature

Parameters

Returns

​sendStdin()

Parameters

Returns

​streamInput()

Parameters

Returns

Throws

Throws

Example

​Pty

​Constructors

Parameters

Returns

​Methods

​connect()

Parameters

Returns

​create()

Parameters

Returns

​kill()

Parameters

Returns

​resize()

Parameters

Returns

​sendInput()

Parameters

Returns

​streamInput()

Parameters

Returns

Throws

Throws

Example

​Interfaces

​CommandRequestOpts

​Extended by

​Properties

​requestTimeoutMs?

Default

CommandInputHandle

Methods

close()

send()

Commands

Constructors

Methods

closeStdin()

connect()

kill()

list()

run()

sendStdin()

streamInput()

Pty

Constructors

Methods

connect()

create()

kill()

resize()

sendInput()

streamInput()

Interfaces

CommandRequestOpts

Extended by

Properties

requestTimeoutMs?

signal?

CommandStartOpts

Properties

background?

cwd?

envs?

onStderr()?

onStdout()?

requestTimeoutMs?

signal?

stdin?

timeoutMs?

user?

CommandStreamInputOpts

Properties

signal?

timeoutMs?

ProcessInfo

Properties

args

cmd

cwd?

envs

pid

tag?

Type Aliases

CommandConnectOpts