Sandbox Commands

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

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.

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.

On this page