# Code execution & sandbox

When the assistant runs a shell command, a Python cell, or a build, it does so inside a managed sandbox — not on the host serving the API. This page documents **where** that execution happens (backends), **how isolated** it is, and the **exact tools** the agent uses, with their parameters and return shapes.

**Backend selection is platform-managed**
Unlike caller-selectable backends in some agents, the execution backend here is chosen by the platform per deployment, not by the API request. You write the same tool calls regardless of backend; the isolation tier is an operational guarantee, not a parameter.

## Execution backends

The active backend is configured via the `SANDBOX_BACKEND` setting (a comma-separated fallback list; the first entry is primary). Every backend exposes the same tool surface — only the isolation and persistence characteristics differ.

| Backend | What it is | Isolation | Use case |
| --- | --- | --- | --- |
| `e2b` | Managed cloud sandbox (default) | Full VM isolation, per-session filesystem | Default for hosted runs |
| `firecracker` | Firecracker microVM | Hardware-virtualized microVM, UFFD memory, pooled networking | Strongest isolation, fast cold-start |
| `superserve` | Managed agents-SDK runtime | Provider-managed container | Managed scaling |
| `blaxel` | Managed agents-SDK runtime | Provider-managed container | Managed scaling |
| `local` | This host | Workspace bind-jail + git staging jail | Trusted self-host / dev only |

## Isolation & containment

Containerized and microVM backends run under a containment profile, not a bare shell:

- **Filesystem jail** — file access is confined to the session workspace; path traversal outside the root is rejected before any I/O.
- **Egress proxy** — outbound network goes through a controlled egress path rather than raw host networking.
- **Per-session filesystem** — each session gets its own workspace; installed packages and `cwd` changes persist across tool calls within a session.
- **microVM tier** — on `firecracker`, the workload runs in a hardware-virtualized microVM with its own kernel, isolated from the host and from other sessions.

**local backend is not a sandbox**
`SANDBOX_BACKEND=local` runs on the host with only a workspace bind-jail and git staging jail. Use it for trusted self-hosted or development setups — never for untrusted input.

## Tools

### `sandbox_bash` — run shell / Python

One-shot command execution in the sandbox. Returns captured streams plus any files written to the workspace.

<ParamTable
    rows={[
        { name: "command", type: "string", required: true, description: "Shell command to execute." },
        { name: "description", type: "string", description: "Short human-readable label of what the command does, e.g. 'Installing dependencies'." },
        { name: "timeout_seconds", type: "int (1–3600)", description: "Command timeout. Default 60s; raise for long installs, builds, or data exports." },
        { name: "cwd", type: "string", description: "Working directory (e.g. /workspace). Default: sandbox home." },
    ]}
/>

Returns:

| Field | Meaning |
| --- | --- |
| `stdout` / `stderr` | Captured output streams. |
| `exit_code` | Process exit code. |
| `truncated` | `true` if output was clipped to the size limit. |
| `files` / `file_count` | Files produced in the workspace by this command. |
| `local_paths` | Map of workspace files to retrievable paths. |

### `repl_execute` — persistent Python REPL

A Jupyter-like Python session that keeps state across calls, with built-in helpers (`peek`, `grep`, `chunk_indices`, `llm_query`, `FINAL`) for working over large data without re-loading it each turn.

### `exec_command` — interactive terminal (PTY)

Runs a command in a PTY session. Commands that finish return `stdout` + `exit_code` directly; long-lived processes (servers, REPLs, watchers) stay alive and return a `session_id` you keep feeding via `write_stdin`.

<ParamTable
    rows={[
        { name: "command", type: "string", required: true, description: "Command to run in a PTY." },
        { name: "rows", type: "int (1–1000)", description: "PTY rows. Default 24." },
        { name: "cols", type: "int (1–1000)", description: "PTY columns. Default 80." },
        { name: "grace_seconds", type: "float", description: "How long to wait for a quick command to finish before returning a live session_id." },
    ]}
/>

Returns `session_id`, `pid`, `stdout`, `cursor`, `status`, `exit_code`, `alive` — the `cursor` lets the next read pick up exactly where the last one left off.

### `write_stdin` — drive a live session

Sends characters to the stdin of a still-running `exec_command` session and reads fresh output. Append `\n` to submit a line.

<ParamTable
    rows={[
        { name: "session_id", type: "string", required: true, description: "Session id from a prior exec_command that is still alive." },
        { name: "input", type: "string", required: true, description: "Characters to write to stdin. Append \\n to submit a line." },
        { name: "since", type: "int", description: "Cursor from the previous read; returns only output produced after it." },
        { name: "wait_seconds", type: "float", description: "How long to wait for new output before returning." },
    ]}
/>

### `edit_file` — surgical file edits

Search-and-replace edits in sandbox files, with a fuzzy-matching fallback when the target text has drifted slightly.

### `bsl_check` — 1C (BSL) static analysis

Runs `bsl-language-server` over 1C code. Point it at a `.bsl` / `.os` file or a configuration-export folder; returns diagnostics.

**Full tool list**
This page covers the code-execution tools. For the complete catalog across all categories (web, memory, connectors, media, …) see <a href="/docs/agents#available-tools">Agents → Available tools</a>.