Documentation

Commands

Module for starting and interacting with commands in the sandbox.

Constructors

new Commands(
   transport: Transport, 
   connectionConfig: ConnectionConfig, 
   metadata: object): Commands

Parameters

Parameter	Type
`transport`	`Transport`
`connectionConfig`	`ConnectionConfig`
`metadata`	{ `version`: `string`; }
`metadata.version`	`string`

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<CommandHandle | CommandResult>

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<CommandHandle | CommandResult> 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>

Pty

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

Constructors

new Pty(
   transport: Transport, 
   connectionConfig: ConnectionConfig, 
   metadata: object): Pty

Parameters

Parameter	Type
`transport`	`Transport`
`connectionConfig`	`ConnectionConfig`
`metadata`	{ `version`: `string`; }
`metadata.version`	`string`

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, "signal" | "requestTimeoutMs">): 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`, `"signal"` \| `"requestTimeoutMs"`>	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, "signal" | "requestTimeoutMs">): 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`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<void>

sendInput()

sendInput(
   pid: number, 
   data: Uint8Array, 
opts?: Pick<ConnectionOpts, "signal" | "requestTimeoutMs">): 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`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<void>

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?

```ts
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?

```ts
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)

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.

​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

​Pty

​Constructors

Parameters

Returns

​Methods

​connect()

Parameters

Returns

​create()

Parameters

Returns

​kill()

Parameters

Returns

​resize()

Parameters

Returns

​sendInput()

Parameters

Returns

​Interfaces

​CommandRequestOpts

​Extended by

​Properties

​requestTimeoutMs?

Default

​cwd?

Default

​envs?

Default

​onStderr()?

Parameters

Returns

​onStdout()?

Parameters

Returns

​requestTimeoutMs?

Default

​signal?

​stdin?

Default

​timeoutMs?

Default

​user?

Default

​ProcessInfo

​Properties

​args

​cmd

​cwd?

Commands

Constructors

Methods

closeStdin()

connect()

kill()

list()

run()

sendStdin()

Pty

Constructors

Methods

connect()

create()

kill()

resize()

sendInput()

Interfaces

CommandRequestOpts

Extended by

Properties

requestTimeoutMs?

cwd?

envs?

onStderr()?

onStdout()?

requestTimeoutMs?

signal?

stdin?

timeoutMs?

user?

ProcessInfo

Properties

args

cmd

cwd?

envs

pid

tag?

Type Aliases

CommandConnectOpts