> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell

> The bash tool runs a command in the sandbox and returns buffered stdout, stderr, and an exit code.

The **`bash`** tool is how the agent runs commands on the [computer](https://vetta.sh/docs/computer/index.md). Each call executes `bash -c <command>` in a **non-login shell**, so a `cwd` you pass is honored as the working directory for that command. It is a single request/response — not a stream.

> [!NOTE]
>
> Exec on a **sleeping** computer wakes it automatically. Exec on a **parked** computer is **rejected** — resume it first. See [lifecycle](https://vetta.sh/docs/computer/sandbox.md#lifecycle).

## Examples

```bash CLI theme={"system"}
vetta computer exec box -- "ls -la /workspace"

# with a timeout; cd inside the command, there is no --cwd
vetta computer exec box --command "cd /workspace && npm test" --timeout-ms 30000
```

```typescript TypeScript theme={"system"}
const result = await vetta.computers.exec(computer.id, {
  command: "npm test",
  cwd: "/workspace",
  env: { CI: "1" },        // this call only; not persisted
  timeoutMs: 30_000,
});

console.log(result.exitCode, result.stdout);
```

```bash cURL theme={"system"}
curl https://api.vetta.sh/v1/computers/$COMPUTER_ID/exec \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm test",
    "cwd": "/workspace",
    "env": { "CI": "1" },
    "timeout_ms": 30000
  }'
```

## Output caps at a glance

| Field | Cap | Behavior beyond cap |
| - | - | - |
| `stdout` | 262,144 chars | Truncated |
| `stderr` | 262,144 chars | Truncated |

> [!TIP]
>
> When you expect large output, redirect it to a file (`… > /workspace/out.log 2>&1`) and read the parts you need with the [filesystem](https://vetta.sh/docs/computer/filesystem.md) tools instead of returning it all through `stdout`.

## Fields

**command** `string` *required*

The command line to run. Executed as `bash -c <command>`.

**cwd** `string`

Working directory for this command. Because the shell is non-login, `cwd` is respected for the call.

**env** `object`

Environment variables for **this call only**. They are **not persisted** — the next `bash` call starts without them. There is no create-time environment injection.

**timeout\_ms** `integer`

Maximum time to wait before the command is killed and the call returns.

> [!WARNING]
>
> `env` is per-call and ephemeral. There is no way to bake environment variables into a computer at create time. With the coming egress pinning, secrets are supplied by the [vault](https://vetta.sh/docs/identity/vault.md) at the network boundary rather than as sandbox env vars — see [Networking](https://vetta.sh/docs/computer/networking.md#egress-pinning-coming-soon).

## Response

The command is run to completion and its output is **buffered**, then returned together:

**stdout** `string`

Buffered standard output. Capped at **262,144 characters**; output beyond the cap is truncated.

**stderr** `string`

Buffered standard error, capped at **262,144 characters** independently of `stdout`.

**exit\_code** `integer`

The process exit code.

> [!NOTE]
>
> The `bash` tool is **not streaming**. stdout and stderr are collected in full (up to the cap) and returned once the command exits or `timeout_ms` elapses. For long-running work, have the command write progress to a file and poll it with [`read`](https://vetta.sh/docs/computer/filesystem).

> [card] [Next: browser](https://vetta.sh/docs/computer/browser.md)
>
> Drive a real, managed browser scoped to an allow-list of domains.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.