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

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, returnsCommandResult`

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>

---

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, "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, "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, "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, "requestTimeoutMs">	connection options.

Returns

Promise<void>

sendInput()

sendInput(
   pid: number, 
   data: Uint8Array, 
opts?: Pick<ConnectionOpts, "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, "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

***

### 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

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.