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`	`object`
`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()

run(cmd, opts)

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.

run(cmd, opts)

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.

run(cmd, opts)

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, 
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`	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`	`object`
`metadata.version`	`string`

Returns

Pty

Methods

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

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.

​Commands

​Constructors

Parameters

Returns

​Methods

​connect()

Parameters

Returns

​kill()

Parameters

Returns

​list()

Parameters

Returns

​run()

run(cmd, opts)

Parameters

Returns

run(cmd, opts)

Parameters

Returns

run(cmd, opts)

Parameters

Returns

​sendStdin()

Parameters

Returns

​Pty

​Constructors

Parameters

Returns

​Methods

​create()

Parameters

Returns

​kill()

Parameters

Returns

​resize()

Parameters

Returns

​sendInput()

Parameters

Returns

​Interfaces

​CommandRequestOpts

​Extended by

​Properties

​requestTimeoutMs?

Default

​CommandStartOpts

​Properties

​background?

​cwd?

Default

​envs?

Default

​onStderr()?

Parameters

Returns

​onStdout()?

Parameters

Returns

​requestTimeoutMs?

Default

​stdin?

Default

​timeoutMs?

Default

​user?

Default

​ProcessInfo

​Properties

​args

​cmd

​cwd?

​envs

​pid

​tag?

​Type Aliases

Commands

Constructors

Methods

connect()

kill()

list()

run()

sendStdin()

Pty

Constructors

Methods

create()

kill()

resize()

sendInput()

Interfaces

CommandRequestOpts

Extended by

Properties

requestTimeoutMs?

CommandStartOpts

Properties

background?

cwd?

envs?

onStderr()?

onStdout()?

requestTimeoutMs?

stdin?

timeoutMs?

user?

ProcessInfo

Properties

args

cmd

cwd?

envs

pid

tag?

Type Aliases

CommandConnectOpts