# Sandbox Commands (/v2.29.1/sandbox-commands)

<!-- agent-signals: reading_time_min: 9 · est_tokens: 4002 · updated: 2026-07-30 -->
Related: [Errors](/v2.29.1/errors.md), [Sandbox](/v2.29.1/sandbox.md), [Sandbox Filesystem](/v2.29.1/sandbox-filesystem.md), [Template](/v2.29.1/template.md), [Template Logger](/v2.29.1/template-logger.md), [Template Readycmd](/v2.29.1/template-readycmd.md)

### Commands [#commands]

Module for starting and interacting with commands in the sandbox.

#### Constructors [#constructors]

```ts
new Commands(
   transport: Transport, 
   connectionConfig: ConnectionConfig, 
   metadata: object): Commands
```

###### Parameters [#parameters]

| Parameter          | Type                      |
| ------------------ | ------------------------- |
| `transport`        | `Transport`               |
| `connectionConfig` | `ConnectionConfig`        |
| `metadata`         | \{ `version`: `string`; } |
| `metadata.version` | `string`                  |

###### Returns [#returns]

`Commands`

#### Methods [#methods]

### closeStdin() [#closestdin]

```ts
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 [#parameters-1]

| 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 [#returns-1]

`Promise`\<`void`>

### connect() [#connect]

```ts
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 [#parameters-2]

| 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 [#returns-2]

`Promise`\<`CommandHandle`>

`CommandHandle` handle to interact with the running command.

### kill() [#kill]

```ts
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 [#parameters-3]

| 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 [#returns-3]

`Promise`\<`boolean`>

`true` if the command was killed, `false` if the command was not found.

### list() [#list]

```ts
list(opts?: CommandRequestOpts): Promise<ProcessInfo[]>
```

List all running commands and PTY sessions.

###### Parameters [#parameters-4]

| Parameter | Type                 | Description         |
| --------- | -------------------- | ------------------- |
| `opts`?   | `CommandRequestOpts` | connection options. |

###### Returns [#returns-4]

`Promise`\<`ProcessInfo`\[]>

list of running commands and PTY sessions.

### run() [#run]

###### Call Signature [#call-signature]

```ts
run(cmd: string, opts?: CommandStartOpts & object): Promise<CommandResult>
```

Start a new command and wait until it finishes executing.

###### Parameters [#parameters-5]

| Parameter | Type                          | Description                       |
| --------- | ----------------------------- | --------------------------------- |
| `cmd`     | `string`                      | command to execute.               |
| `opts`?   | `CommandStartOpts` & `object` | options for starting the command. |

###### Returns [#returns-5]

`Promise`\<`CommandResult`>

`CommandResult` result of the command execution.

###### Call Signature [#call-signature-1]

```ts
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 [#parameters-6]

| Parameter | Type                          | Description                      |
| --------- | ----------------------------- | -------------------------------- |
| `cmd`     | `string`                      | command to execute.              |
| `opts`    | `CommandStartOpts` & `object` | options for starting the command |

###### Returns [#returns-6]

`Promise`\<`CommandHandle`>

`CommandHandle` handle to interact with the running command.

###### Call Signature [#call-signature-2]

```ts
run(cmd: string, opts?: CommandStartOpts & object): Promise<CommandHandle | CommandResult>
```

Start a new command.

###### Parameters [#parameters-7]

| 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 [#returns-7]

`Promise`\<`CommandHandle` | `CommandResult`>

Either a `CommandHandle` or a `CommandResult` (depending on `opts.background`).

### sendStdin() [#sendstdin]

```ts
sendStdin(
   pid: number, 
   data: string | Uint8Array<ArrayBufferLike>, 
opts?: CommandRequestOpts): Promise<void>
```

Send data to command stdin.

###### Parameters [#parameters-8]

| 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 [#returns-8]

`Promise`\<`void`>

***

### Pty [#pty]

Module for interacting with PTYs (pseudo-terminals) in the sandbox.

#### Constructors [#constructors-1]

```ts
new Pty(
   transport: Transport, 
   connectionConfig: ConnectionConfig, 
   metadata: object): Pty
```

###### Parameters [#parameters-9]

| Parameter          | Type                      |
| ------------------ | ------------------------- |
| `transport`        | `Transport`               |
| `connectionConfig` | `ConnectionConfig`        |
| `metadata`         | \{ `version`: `string`; } |
| `metadata.version` | `string`                  |

###### Returns [#returns-9]

`Pty`

#### Methods [#methods-1]

### connect() [#connect-1]

```ts
connect(pid: number, opts?: PtyConnectOpts): Promise<CommandHandle>
```

Connect to a running PTY.

###### Parameters [#parameters-10]

| 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 [#returns-10]

`Promise`\<`CommandHandle`>

handle to interact with the PTY.

### create() [#create]

```ts
create(opts: PtyCreateOpts): Promise<CommandHandle>
```

Create a new PTY (pseudo-terminal).

###### Parameters [#parameters-11]

| Parameter | Type            | Description                   |
| --------- | --------------- | ----------------------------- |
| `opts`    | `PtyCreateOpts` | options for creating the PTY. |

###### Returns [#returns-11]

`Promise`\<`CommandHandle`>

handle to interact with the PTY.

### kill() [#kill-1]

```ts
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 [#parameters-12]

| Parameter | Type                                                          | Description            |
| --------- | ------------------------------------------------------------- | ---------------------- |
| `pid`     | `number`                                                      | process ID of the PTY. |
| `opts`?   | `Pick`\<`ConnectionOpts`, `"signal"` \| `"requestTimeoutMs"`> | connection options.    |

###### Returns [#returns-12]

`Promise`\<`boolean`>

`true` if the PTY was killed, `false` if the PTY was not found.

### resize() [#resize]

```ts
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 [#parameters-13]

| 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 [#returns-13]

`Promise`\<`void`>

### sendInput() [#sendinput]

```ts
sendInput(
   pid: number, 
   data: Uint8Array, 
opts?: Pick<ConnectionOpts, "signal" | "requestTimeoutMs">): Promise<void>
```

Send input to a PTY.

###### Parameters [#parameters-14]

| 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 [#returns-14]

`Promise`\<`void`>

## Interfaces [#interfaces]

### CommandRequestOpts [#commandrequestopts]

Options for sending a command request.

#### Extended by [#extended-by]

* `CommandStartOpts`

#### Properties [#properties]

### requestTimeoutMs? [#requesttimeoutms]

```ts
optional requestTimeoutMs: number;
```

Timeout for requests to the API in **milliseconds**.

###### Default [#default]

```ts
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? [#cwd]

```ts
optional cwd: string;
```

Working directory for the command.

###### Default [#default-1]

```ts
// home directory of the user used to start the command
```

### envs? [#envs]

```ts
optional envs: Record<string, string>;
```

Environment variables used for the command.

This overrides the default environment variables from `Sandbox` constructor.

###### Default [#default-2]

`{}`

### onStderr()? [#onstderr]

```ts
optional onStderr: (data: string) => void | Promise<void>;
```

Callback for command stderr output.

###### Parameters [#parameters-15]

| Parameter | Type     |
| --------- | -------- |
| `data`    | `string` |

###### Returns [#returns-15]

`void` | `Promise`\<`void`>

### onStdout()? [#onstdout]

```ts
optional onStdout: (data: string) => void | Promise<void>;
```

Callback for command stdout output.

###### Parameters [#parameters-16]

| Parameter | Type     |
| --------- | -------- |
| `data`    | `string` |

###### Returns [#returns-16]

`void` | `Promise`\<`void`>

### requestTimeoutMs? [#requesttimeoutms-1]

```ts
optional requestTimeoutMs: number;
```

Timeout for requests to the API in **milliseconds**.

###### Default [#default-3]

```ts
60_000 // 60 seconds
```

### signal? [#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`.

### stdin? [#stdin]

```ts
optional stdin: boolean;
```

If true, command stdin is kept open and you can send data to it using Commands.sendStdin or CommandHandle.sendStdin.

###### Default [#default-4]

```ts
false
```

### timeoutMs? [#timeoutms]

```ts
optional timeoutMs: number;
```

Timeout for the command in **milliseconds**.

###### Default [#default-5]

```ts
60_000 // 60 seconds
```

### user? [#user]

```ts
optional user: string;
```

User to run the command as.

###### Default [#default-6]

`default Sandbox user (as specified in the template)`

***

### ProcessInfo [#processinfo]

Information about a command, PTY session or start command running in the sandbox as process.

#### Properties [#properties-1]

### args [#args]

```ts
args: string[];
```

Command arguments.

### cmd [#cmd]

```ts
cmd: string;
```

Command that was executed.

### cwd? [#cwd-1]

```ts
optional cwd: string;
```

Executed command working directory.

### envs [#envs-1]

```ts
envs: Record<string, string>;
```

Environment variables used for the command.

### pid [#pid]

```ts
pid: number;
```

Process ID.

### tag? [#tag]

```ts
optional tag: string;
```

Custom tag used for identifying special commands like start command in the custom template.

## Type Aliases [#type-aliases]

### CommandConnectOpts [#commandconnectopts]

```ts
type CommandConnectOpts = Pick<CommandStartOpts, "onStderr" | "onStdout" | "timeoutMs"> & CommandRequestOpts;
```

Options for connecting to a command.