# E2B Sandboxes

> Run agent code in isolated E2B cloud sandboxes with your own API key, command execution, file access, and session-scoped lifecycle management.

Source: <https://everruns.com/docs/capabilities/e2b/>

|                  |                                                                              |
| ---------------- | ---------------------------------------------------------------------------- |
| **ID**           | `e2b`                                                                        |
| **Category**     | Sandboxes                                                                    |
| **Features**     | None                                                                         |
| **Dependencies** | [`session_storage`](https://everruns.com/docs/capabilities/session-storage/) |

Run code in cloud sandboxes powered by [E2B](https://e2b.dev/docs). An agent can create, pause, resume, delete, and work in several isolated Linux sandboxes per session. Sandboxes are tracked per session.

You bring your own E2B API key. There is no platform-owned or environment-variable fallback, so sandbox costs and quotas stay in your own E2B account.

## Set up

1. In the [E2B Dashboard](https://e2b.dev/dashboard), create an API key and copy it.
2. In Everruns, open **Settings** > **Connections**, find **E2B**, select **Connect**, and paste the key.

Every E2B operation requires a user-provided key. If none is configured, the agent shows an inline connection prompt.

## Tools

### `e2b_create_sandbox`

Create a new E2B sandbox. Returns `sandbox_id` and connection details.

| Parameter         | Type    | Required | Description                                                       |
| ----------------- | ------- | -------- | ----------------------------------------------------------------- |
| `title`           | string  | no       | Human-readable sandbox name                                       |
| `template`        | string  | no       | E2B template ID (default `base`)                                  |
| `timeout_seconds` | integer | no       | Sandbox TTL in seconds (default `3600`)                           |
| `env_vars`        | object  | no       | Environment variables injected into the sandbox                   |
| `upload_files`    | array   | no       | `{session_path, sandbox_path}` pairs to copy from session storage |

### `e2b_exec`

Execute a shell command in a sandbox, capturing stdout, stderr, and the exit code.

| Parameter    | Type    | Required | Description                     |
| ------------ | ------- | -------- | ------------------------------- |
| `sandbox_id` | string  | yes      | Target sandbox                  |
| `command`    | string  | yes      | Shell command to run            |
| `cwd`        | string  | no       | Working directory               |
| `timeout_ms` | integer | no       | Command timeout in milliseconds |

### `e2b_read_file`

Read a text file from a sandbox filesystem.

| Parameter    | Type    | Required | Description                       |
| ------------ | ------- | -------- | --------------------------------- |
| `sandbox_id` | string  | yes      | Target sandbox                    |
| `path`       | string  | yes      | File path                         |
| `offset`     | integer | no       | Line offset to start reading from |
| `limit`      | integer | no       | Maximum number of lines to return |

### `e2b_write_file`

Write a text file into a sandbox filesystem.

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `sandbox_id` | string | yes      | Target sandbox |
| `path`       | string | yes      | File path      |
| `content`    | string | yes      | File content   |

### `e2b_list_sandboxes`

List all E2B sandboxes created in the current session. Takes no parameters.

### `e2b_manage_sandbox`

Pause, resume, or delete an E2B sandbox.

| Parameter         | Type    | Required | Description                    |
| ----------------- | ------- | -------- | ------------------------------ |
| `sandbox_id`      | string  | yes      | Target sandbox                 |
| `action`          | string  | yes      | `pause`, `resume`, or `delete` |
| `timeout_seconds` | integer | no       | Timeout to apply when resuming |

## How it works

E2B exposes two surfaces, and the capability uses both:

* **Management API** (`api.e2b.app`): sandbox lifecycle, metadata, and timeout control.
* **envd sandbox endpoint**: in-sandbox file access and command execution.

Per-sandbox state (sandbox ID, domain, access token, workspace path, timeout) is stored in encrypted session secrets and registered as a leased resource, so orphaned sandboxes are cleaned up on the worker side. Every sandbox is tagged with Everruns ownership metadata (session, harness, org, and agent IDs) for dashboard traceability and audit review.

File operations target the sandbox filesystem, not the session workspace. Each sandbox has internet access. Use `e2b_manage_sandbox` to delete sandboxes when you are done.

## Security

* API keys resolve fresh from your user connection on each tool call. They are never stored in sandbox state or env vars, and never appear in tool output.
* envd access tokens are session-scoped and stored only in encrypted session secrets (AES-256-GCM envelope encryption).
* Sandbox isolation depends on E2B’s runtime boundaries plus Everruns session-scoped secret lookups.
* E2B timeouts and auto-pause, plus Everruns leased-resource cleanup, limit resource leaks.

## See also

* [Storage](https://everruns.com/docs/capabilities/session-storage/): API key and state persistence.
* [E2B documentation](https://e2b.dev/docs)
* [Integrations](https://everruns.com/docs/integrations/): every vendor integration.
* [Capabilities Overview](https://everruns.com/docs/capabilities/)