# Shell

Run a single bash command in an isolated sandbox container and return stdout / stderr / exit code.

## Overview

`shell` runs on the same isolated sandbox that powers `code_interpreter`, with `language: "bash"`. The LLM calls it with a `command` string; the command runs in the sandbox and the captured output is fed back to the model.

Use it for short, transient data processing:

- `jq` / `grep` / `awk` over text the model already has.
- `base64` / `openssl` for encoding or hashing.
- Quick `curl` (only with **Allow internet** explicitly on, and only for trusted commands).
- Spawning a one-shot CLI that ships with the sandbox image.

If you find yourself reaching for shell to write Python, use `code_interpreter` instead — it streams variables back more cleanly.

## Security model

The sandbox is the **single most defensive surface in the product**:

- **Ephemeral container** — destroyed after each call. There is no shared filesystem between calls or between users.
- **Kernel-level isolation** — the container does not see the host kernel; system calls are intercepted and confined.
- **No network by default** — outbound connections are blocked. Enable **Allow internet** per tool only if you have to, and only for commands you fully trust.
- **No host metadata exposure** — the sandbox image does not mount AWS IMDS, GCP metadata, Docker socket, or any cloud credential. Even with internet on, the agent cannot reach `169.254.169.254`.
- **Hard wall-clock timeout** — default 60 s, max 600 s. Capped server-side regardless of what the model passes.

If your workspace administrator has disabled unsafe agent tools, this tool is unavailable — agents simply do not see it.

## Configuration

| Field | Values | Notes |
| --- | --- | --- |
| Timeout (seconds) | 5–600 | Default 60. Hard kill after this. |
| Working directory | path string | Default `/workspace` in the modal, `/tmp` server-side fallback. The directory exists in the sandbox image. |
| Allow internet | boolean | Off by default. **Risky** — UI shows an amber warning when enabled. |

## Example

User turn: *"Hash this string with SHA-256: ‘hello world'."*

Model issues:

```json
{ "command": "printf 'hello world' | sha256sum" }
```

Response fed back to the model:

```json
{
  "status": "completed",
  "exit_code": 0,
  "stdout": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9  -\n",
  "stderr": ""
}
```

The model then replies with the hash.

## Best practices

- **One command per call.** Chain with `&&` if you must, but the model debugs better when each tool call has a single purpose.
- **Quote untrusted input.** If the agent interpolates user text into a command, instruct it to wrap with single quotes. Better: use `function` for anything reaching a real system.
- **Leave `Allow internet` off.** The whole value of the sandbox collapses if it can call out.

## Gotchas

- The sandbox is destroyed after each call — files written to `/tmp` do not survive. Pipe directly to stdout if you want the model to see the result.
- `stderr` is returned but the LLM frequently ignores it. If a command fails silently, look at `exit_code`.
- The sandbox image is intentionally small; tools like `docker`, `kubectl`, `aws` are **not** present.

---

*Source: https://agentbuilder.systalink.sn/docs/tool-shell — human documentation.*
*Other language: [/docs-md/fr/tool-shell.md](/docs-md/fr/tool-shell.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*