Skip to main content

​
Commands

Module for starting and interacting with commands in the sandbox.

​
Constructors

new Commands(
   transport: Transport, 
   connectionConfig: ConnectionConfig, 
   metadata: object): Commands
Parameters
ParameterType
transportTransport
connectionConfigConnectionConfig
metadata{ version: string; }
metadata.versionstring
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
ParameterTypeDescription
pidnumberprocess ID of the command. You can get the list of running commands using Commands.list.
opts?CommandRequestOptsconnection 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
ParameterTypeDescription
pidnumberprocess ID of the command to connect to. You can get the list of running commands using Commands.list.
opts?CommandConnectOptsconnection 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
ParameterTypeDescription
pidnumberprocess ID of the command. You can get the list of running commands using Commands.list.
opts?CommandRequestOptsconnection 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
ParameterTypeDescription
opts?CommandRequestOptsconnection 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
ParameterTypeDescription
cmdstringcommand to execute.
opts?CommandStartOpts & objectoptions 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
ParameterTypeDescription
cmdstringcommand to execute.
optsCommandStartOpts & objectoptions 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
ParameterTypeDescription
cmdstringcommand to execute.
opts?CommandStartOpts & objectoptions for starting the command. - opts.background: true - runs in background, returns CommandHandle - `opts.background: falseundefined- waits for completion, returnsCommandResult`
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
ParameterTypeDescription
pidnumberprocess ID of the command. You can get the list of running commands using Commands.list.
datastring | Uint8Array<ArrayBufferLike>data to send to the command.
opts?CommandRequestOptsconnection 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
ParameterType
transportTransport
connectionConfigConnectionConfig
metadata{ version: string; }
metadata.versionstring
Returns
Pty

​
Methods

​
connect()

connect(pid: number, opts?: PtyConnectOpts): Promise<CommandHandle>
Connect to a running PTY.
Parameters
ParameterTypeDescription
pidnumberprocess ID of the PTY to connect to. You can get the list of running PTYs using Commands.list.
opts?PtyConnectOptsconnection options.
Returns
Promise<CommandHandle> handle to interact with the PTY.

​
create()

create(opts: PtyCreateOpts): Promise<CommandHandle>
Create a new PTY (pseudo-terminal).
Parameters
ParameterTypeDescription
optsPtyCreateOptsoptions 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
ParameterTypeDescription
pidnumberprocess 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
ParameterTypeDescription
pidnumberprocess ID of the PTY.
size{ cols: number; rows: number; }new size of the PTY.
size.colsnumber-
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
ParameterTypeDescription
pidnumberprocess ID of the PTY.
dataUint8Arrayinput 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
ParameterType
datastring
Returns
void | Promise<void>

​
onStdout()?

optional onStdout: (data: string) => void | Promise<void>;
Callback for command stdout output.
Parameters
ParameterType
datastring
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.