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