# Sandboxes API reference

> The endpoints and create fields that Serenity Edge Sandboxes support, what differs from the E2B API, the public template, the sandbox lifecycle, timeouts, pause and resume, commands and ports.

Source: https://docs.serenityedge.ai/docs/sandboxes/api-reference/

> **Private preview**
> 
> Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)). This page lists what the API accepts and refuses today; a range of supported SDK versions is not published yet. Changes will be announced in the [release notes](https://docs.serenityedge.ai/release-notes/).

The sandbox API is compatible with the E2B API. This page lists the endpoints and fields that Serenity Edge supports and every place where it answers differently. For the meaning of each `error_code`, see [Errors](https://docs.serenityedge.ai/docs/sandboxes/errors/).

## Base URL and authentication

|  |  |
| --- | --- |
| Domain (`E2B_DOMAIN`) | `serenityedge.ai` |
| Control API | `https://api.serenityedge.ai`, the host of the inference API. The paths are the E2B API's ([below](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#endpoints)), not under `/v1` |
| Inside a sandbox | `https://<port>-<sandbox id>.<sandbox domain>`, where the sandbox domain is the `domain` field of the create and connect answers (`vlc1.serenitysandboxes.cloud` in the preview). You do not set it |
| Authentication | `X-API-Key: <your Serenity Edge API key>` |

-   The key is the same Serenity Edge API key that you use for inference. Its account must have Sandboxes enabled (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)).
-   `Authorization: Bearer <key>` is also accepted when `X-API-Key` is absent.
-   A missing or unknown key gets HTTP 401 with `error_code: "edge_unauthorized"`, and a Serenity Edge API key whose account does not have Sandboxes enabled gets HTTP 403 with `error_code: "edge_sandboxes_not_enabled"`.
-   Each key may have 8 requests to the control API in flight and send it 120 requests a minute, apart from the limits of the inference API (see [Request limits](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/#request-limits)).
-   Requests inside a sandbox (commands, files, a terminal, ports) do not go to the control API and do not carry your API key. They go to the sandbox's own domain and carry the sandbox's own tokens, `envdAccessToken` and `trafficAccessToken`, which the create and connect answers return with `domain`. The SDKs handle the calls for commands, files and a terminal for you (see [Running commands and opening a terminal](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#running-commands-and-opening-a-terminal)).
-   Request bodies are JSON, at most 1 MiB. A larger body gets `413 edge_request_too_large`.

## Endpoints

### Supported

| Endpoint | What it does | Notes |
| --- | --- | --- |
| `POST /sandboxes`, `POST /v2/sandboxes` | Create a sandbox | Only the [create fields](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#create-fields) below. Counts against your running and creates-per-minute [limits](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/) |
| `GET /sandboxes`, `GET /v2/sandboxes` | List your sandboxes | The `metadata` query parameter filters the list, and on `/v2/sandboxes` so does `state` (`running`, `paused`) |
| `GET /sandboxes/{sandboxID}` | Read one sandbox: `state`, `cpuCount`, `memoryMB`, `diskSizeMB`, `startedAt`, `endAt`, `metadata`, `domain` |  |
| `GET /sandboxes/metrics`, `GET /sandboxes/{sandboxID}/metrics` | Read sandbox metrics | Not available in the preview: an empty list, or HTTP 400 when a start time is given (see [Known issues in the preview](https://docs.serenityedge.ai/docs/sandboxes/overview/#known-issues-in-the-preview)) |
| `POST /sandboxes/{sandboxID}/timeout` | Set a new timeout, counted from now | See [Timeouts](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#timeouts) |
| `POST /sandboxes/{sandboxID}/refreshes` | Extend the life of a running sandbox |  |
| `POST /sandboxes/{sandboxID}/pause` | Pause a running sandbox | See [Pause and resume](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#pause-and-resume) |
| `POST /sandboxes/{sandboxID}/connect`, `POST /v2/sandboxes/{sandboxID}/connect` | Connect to a sandbox; resumes it when it is paused | A resume counts against your running limit. The body may not carry network fields |
| `POST /sandboxes/{sandboxID}/resume` | Resume a paused sandbox (deprecated in the E2B API; prefer connect) | As connect. A `cpuCount` above your account's maximum gets `400 edge_shape_limit` |
| `POST /sandboxes/{sandboxID}/fork` | Start up to 100 copies of a running sandbox | Each copy counts against both limits. The body may not carry network fields |
| `DELETE /sandboxes/{sandboxID}` | Kill a running or paused sandbox |  |
| `GET /templates`, `GET /v2/templates`, `GET /default-templates`, `GET /templates/{templateID}`, `GET /templates/aliases/{alias}` | Read templates | Read only |
| `POST /sandboxes/{sandboxID}/snapshots` | Save a sandbox as a private template of your account | Only on accounts with templates enabled, on request; see [Save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/) |
| `GET /snapshots` | List your account's templates | As above |
| `DELETE /templates/{templateID}` | Delete one of your account's templates | As above. Until a fix, delete by the bare name, without your account's namespace (see [Known issues in the preview](https://docs.serenityedge.ai/docs/sandboxes/overview/#known-issues-in-the-preview)) |

The routes that the preview's tests cover end to end are create, list, pause, connect and kill, the calls of the [quickstart](https://docs.serenityedge.ai/docs/sandboxes/quickstart/). The other routes in this table are passed on to the sandbox service as they are.

### Refused

These routes exist in the E2B API and are refused on Serenity Edge. None of them reaches a sandbox.

| Endpoint | Answer | Why |
| --- | --- | --- |
| `PUT /sandboxes/{sandboxID}/network` | `403 edge_egress_managed` | Outbound access is set by Serenity Edge and cannot be changed by the client (see [Outbound access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#outbound-access)) |
| `GET /sandboxes/{sandboxID}/logs`, `GET /v2/sandboxes/{sandboxID}/logs` | `403 edge_logs_not_available` | Sandbox logs are not available in the preview. Capture the output of your commands in your client |
| Every write under `/templates`, `/v2/templates` and `/v3/templates` other than the delete of one of your templates, and `/unstable/builds`. On an account without templates enabled, also `POST /sandboxes/{sandboxID}/snapshots` and `DELETE /templates/{templateID}` | `403 edge_template_builds_disabled` | Template builds and changes are not available in the preview; use the public template, or [save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/) |
| Everything else, including `/volumes`, `/secrets`, `/teams`, `/api-keys` and `/events`, and `/snapshots` on an account without templates enabled | `404 edge_route_not_available` | Not part of the sandbox API on Serenity Edge |
| Any request that asks to switch protocols (`Upgrade`) on the control API | `400 edge_upgrade_not_supported` | The control API is plain HTTP requests and answers |

## Create fields

A create accepts only the fields in this table. Any other field with a value is refused with `400 edge_field_not_supported`, and the message names the field. A field set to `null` counts as absent.

| Field | Rule |
| --- | --- |
| `templateID` | Required. The public template: `base`, which the SDKs send when you name no template, or its own name, `edge-agents`. On an account with templates enabled, also the snapshot id of one of its templates (see [Save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/)). Another template gets `403 edge_template_not_allowed` |
| `timeout` | Seconds, a non-negative integer. See [Timeouts](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#timeouts) |
| `metadata` | An object of string values, at most 4,096 bytes in total (see [Metadata](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#metadata)) |
| `envVars` | An object of string values, set as environment variables in the sandbox |
| `autoPause` | A boolean. When `true`, the sandbox is paused at its timeout instead of killed |
| `autoResume` | Only `{"enabled": false}`. `{"enabled": true}` gets `400 edge_field_not_supported`: a paused sandbox is resumed only by a connect or resume call |
| `secure` | Always on. `false` gets `400 edge_field_not_supported` |
| `cpuCount`, `memoryMB` | Optional. Each must equal the template's value, or the create gets `400 edge_shape_limit` (a value below 1 gets `400 edge_invalid_request`). A sandbox runs, and is billed, at its template's size |
| `network` | Only `maskRequestHost` and `httpsPorts` are accepted. `allowPublicTraffic: true` gets `403 edge_public_traffic_not_supported`. `allowOut`, `denyOut`, `dnsServers`, `rules` and `egressProxy` get `403 edge_egress_managed`, empty lists included |
| `allow_internet_access` | Optional. `false` creates a sandbox with no internet access at all (see [Sandboxes with no internet access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#sandboxes-with-no-internet-access)). Leave it out for the default outbound access: `true` gets `403 edge_egress_managed` |

Notes:

-   The fields that an E2B SDK sends on a default create (`templateID`, `timeout`, `metadata`, `envVars`, `secure: true`, `autoPause`) are all accepted.
-   Four values that ask for nothing are ignored, because an SDK may send them by default: `mcp: {}`, `iam: {}`, `volumeMounts: []` and `autoPauseMemory: true`. Any other value of those fields is refused with `400 edge_field_not_supported`, `autoPauseMemory: false` included.
-   Field names are matched without regard to letter case. A body that spells the same field twice gets `400 edge_invalid_request`.

A minimal create:

```bash
curl -sS -X POST "https://api.serenityedge.ai/sandboxes" \
  -H "X-API-Key: $E2B_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateID": "base", "timeout": 300}'
```

### Metadata

-   Metadata is an object of string keys and string values that you attach on create. It comes back when you read or list the sandbox, and you can filter a list by it.
-   Its size is measured as compact JSON with the keys sorted. Over 4,096 bytes, the create gets `400 edge_metadata_too_large`. Metadata is never truncated.
-   Keys that start with `serenity.` or `edge.`, in any letter case, are reserved and get `403 edge_metadata_reserved`. Serenity Edge may add keys of its own that start with `edge.` (for example `edge.egress` on a [sandbox with no internet access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#sandboxes-with-no-internet-access)); they count toward the 4,096 bytes.
-   Metadata is recorded with your usage, so do not put secrets or personal data in it.

### Retrying a create

A create is not idempotent. The `Idempotency-Key` header of the E2B API is not passed on, so a create sent twice makes two sandboxes, and both are billed.

If a create times out on your side, list your sandboxes by metadata before you retry. Give each create a metadata value of your own, for example a task id, and look for it:

```bash
curl -sS "https://api.serenityedge.ai/v2/sandboxes?metadata=task%3D8f2c" \
  -H "X-API-Key: $E2B_API_KEY"
```

The `metadata` parameter is a URL-encoded list of `key=value` pairs (`task=8f2c` above).

## Templates

The preview has one public template, `edge-agents`, maintained by Serenity Edge. Every sandbox is created from it and has its size. It is the default: it also answers to `base`, the id the SDKs send when you name no template, so `Sandbox.create()` uses it, and over HTTP either id works as `templateID`.

|  |  |
| --- | --- |
| Size | 2 vCPUs, 2 GiB of memory and about 26 GiB of disk, of which 20 GiB are free when the sandbox starts |
| System | Ubuntu 24.04. The user is `user`, with the home directory `/home/user` and `sudo` without a password |
| Languages and build tools | Python 3.12 with pip, venv and `uv`; Node.js 26 (LTS) with npm; the .NET 10 SDK; `gcc`, `g++` and `make` |
| Python libraries | Common libraries for data and science, charts, Office documents and PDF, HTML and scraping, and Google APIs; Jupyter kernels and `nbconvert` (no JupyterLab) |
| Documents and media | LibreOffice (headless, with `unoserver`), `pandoc`, `ffmpeg`, ImageMagick, `poppler-utils`, and Tesseract OCR with English and Spanish |
| Command-line tools | `git`, `git-lfs`, the GitHub CLI (`gh`), `ripgrep`, `fd`, `jq`, `curl`, `wget` |
| Browser | Playwright with its Chromium headless shell (headless only) |
| Outbound access | The proxy settings are set in the template, so `pip`, `uv`, `npm`, `curl`, `wget`, `apt`, `gh`, `dotnet` and `git` over HTTPS reach the internet with no configuration (see [Outbound access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#outbound-access)) |

-   **Not included.** Software under the AGPL or a commercial-only licence is left out, PyMuPDF and Ghostscript among them. ImageMagick therefore cannot read or write PDF, PostScript or EPS: use `poppler-utils`, `pypdf`, `pypdfium2` or LibreOffice for PDF. The `vim`, `nano` and `netcat` programs are not installed either.
-   **Installing packages.** `pip install` outside a virtual environment installs into `~/.local`; use `uv venv` for a project. `npm install -g` installs into `~/.npm-global`. Run `sudo apt-get update` before `sudo apt-get install`: the package lists are not in the template.
-   **Versions.** The file `/etc/edge-template-release` in a sandbox names the template's release and its main versions.
-   **Licences.** The GPL programs in the template, such as `pandoc`, `poppler-utils` and `ffmpeg`, are Ubuntu's own packages, unmodified. Their source is in Ubuntu's archive, and each package's licence is in `/usr/share/doc/<package>/copyright` in the sandbox.
-   Building or changing templates is not available in the preview (`403 edge_template_builds_disabled`). Saving a sandbox as a private template of your account, creating sandboxes from it and deleting it are enabled on request, per account (see [Save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/)).
-   The template may change during the preview, for example when its tools are updated. Changes will be announced in the [release notes](https://docs.serenityedge.ai/release-notes/). A new release of the template does not change sandboxes that are already running or paused.
-   To see the size of a sandbox, read `cpuCount`, `memoryMB` and `diskSizeMB` from `GET /sandboxes/{sandboxID}`. `diskSizeMB` is the size of the whole disk, of which 20 GiB are free when the sandbox starts.

## Lifecycle

A sandbox is `running` or `paused`. A killed sandbox no longer exists and is not listed.

| Event | Result | Billing |
| --- | --- | --- |
| Create | `running` | Running price from this moment |
| Pause, or timeout with `autoPause: true` | `paused`: memory, disk and processes are stored | Running price ends, paused price starts |
| Connect or resume | `running` again, with memory, disk and processes as they were | Paused price ends, running price starts |
| Kill, or timeout without `autoPause` | Gone: memory and disk are discarded | Ends |
| Paused for 30 days | Gone: the stored memory and disk are deleted | Ends at the 30 days |
| Platform failure | Gone | Ends at the failure; see [No service level](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/#no-service-level) |

## Timeouts

-   `timeout` is the number of seconds after which a running sandbox ends. It is counted from the call that sets it: the create, a connect, or `POST /sandboxes/{sandboxID}/timeout`, which replaces the previous value.
-   At the timeout the sandbox is killed. With `autoPause: true` on create, it is paused instead.
-   When you leave `timeout` out, the default depends on the route and on the SDK, so set it in every create and connect.
-   A sandbox runs for at most 24 hours.
-   A timeout is the only thing that stops a forgotten sandbox. A spending cap is not offered in the preview.

## Pause and resume

**Pause.** `POST /sandboxes/{sandboxID}/pause` stores the sandbox's memory and disk and stops it. Files, memory and processes are kept: processes are frozen, not ended, and after a resume they continue where they were. Open connections and streams to the sandbox end at the pause.

**Resume.** Connect to the sandbox (`POST /sandboxes/{sandboxID}/connect` with a `timeout`, or `Sandbox.connect` in the SDKs). Connecting to a running sandbox only extends its timeout.

-   A paused sandbox is resumed only by your connect or resume call. Traffic to a paused sandbox does not wake it (`autoResume` cannot be turned on).
-   A resume starts a sandbox, so it counts against your limit of running sandboxes. At the limit it gets `429 edge_concurrency_limit` with `Retry-After`. A connect to a sandbox that is already running is never refused for that limit.
-   **A refused or failed resume leaves the sandbox paused.** Nothing is lost: retry it.
-   A resume that fails with HTTP 500 and a message that the sandbox's files were not found can succeed on a later attempt: retry a few times over the next minutes.

**Durability.** Paused sandboxes are not backed up during the preview. If the site's storage fails, a paused sandbox can be lost, and it then cannot be resumed. Do not keep the only copy of anything in a paused sandbox: copy what you need out before you pause it.

**Expiry.** A sandbox that stays paused for 30 days expires: it is deleted and cannot be resumed. Kill a paused sandbox earlier with `DELETE /sandboxes/{sandboxID}` to stop paying for its storage.

### Maintenance

When Serenity Edge takes a host out of service for maintenance, it pauses the sandboxes running on it. It does not resume them: your client does, with a connect.

-   From your side this looks like a pause that you did not ask for: commands in flight fail, open connections and streams end, and the sandbox's state is `paused`.
-   The pause is billed as any pause, at the paused price, until you resume or kill it.
-   A client that must survive maintenance should, on a connection error, read the sandbox's state and connect again if it is `paused`, retrying a failed resume as described above.

## Running commands and opening a terminal

Commands, files, processes and terminals inside a sandbox are reached over HTTPS, through an agent that runs in every sandbox. The SDKs call it for you at `https://49983-<sandbox id>.<sandbox domain>`, on the sandbox domain the API returned, over HTTPS on port 443 like every other request, and authenticate with the sandbox's own access token (`envdAccessToken`), not with your API key. Your network needs to allow outbound HTTPS to `api.serenityedge.ai` and to the sandbox domain and its subdomains (`*.vlc1.serenitysandboxes.cloud` in the preview), and nothing else.

| To | Use, in the E2B SDKs |
| --- | --- |
| Run a command and read its output, or start it in the background | `sandbox.commands.run` |
| List the running processes, send input to one, or end it | The other methods of `sandbox.commands` |
| Read, write and list files | `sandbox.files`. In the preview, write files under `/home/user`: writing a path under `/tmp` a second time fails (see [Known issues in the preview](https://docs.serenityedge.ai/docs/sandboxes/overview/#known-issues-in-the-preview)) |
| Open an interactive terminal, send it keystrokes and resize it | `sandbox.pty` |

The terminal is a pseudo-terminal (PTY): a shell in the sandbox whose output streams to your client over the same HTTPS connection as commands, with the same token. Use it to give a person, or an agent that expects a terminal, an interactive shell.

-   **There is no SSH access to sandboxes.** Use the SDKs' commands and terminal instead.
-   The preview's end-to-end tests run commands and work with files through the Python SDK. The terminal uses the same connection; it is not part of those tests yet, and neither is the E2B command-line tool.
-   Commands run as the template's user, `user`, in a login shell, so the template's proxy settings apply to them.
-   The connections that stream a command's output or a terminal end when the sandbox is paused, including a pause for [maintenance](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#maintenance). The processes are frozen, not ended: connect to the sandbox again after the resume to reach them.
-   **A command ends at its own timeout.** The SDKs give every command a timeout, 60 seconds by default, and the command is ended when it runs out, in the background too. For a server or another long process, turn it off: `sandbox.commands.run(cmd, background=True, timeout=0)` in Python, `sandbox.commands.run(cmd, { background: true, timeoutMs: 0 })` in JavaScript. The process then runs until it exits, you end it, or the sandbox ends.
-   Commands cannot be sent with curl: the agent speaks a streaming RPC protocol that the SDKs implement.

## Sandbox ports

A process in a sandbox that listens on a port is reachable by name at `https://<port>-<sandbox id>.<sandbox domain>`, on the sandbox domain that the API returns in the `domain` field of the create and connect answers (`vlc1.serenitysandboxes.cloud` in the preview), never under `serenityedge.ai`. Every request must carry the sandbox's traffic access token (`trafficAccessToken` in the same answers) in the `e2b-traffic-access-token` header; a request without it is refused. Sandbox ports cannot be made public in the preview.

The SDKs build the host name for you. For a web server on port 8080 of a sandbox, in Python:

```python
import httpx

host = sandbox.get_host(8080)  # "8080-<sandbox id>.<sandbox domain>"
response = httpx.get(
    f"https://{host}/",
    headers={"e2b-traffic-access-token": sandbox.traffic_access_token},
)
print(response.status_code)
```

In JavaScript:

```javascript
const host = sandbox.getHost(8080); // "8080-<sandbox id>.<sandbox domain>"
const response = await fetch(`https://${host}/`, {
  headers: { "e2b-traffic-access-token": sandbox.trafficAccessToken },
});
console.log(response.status);
```

With curl, take the host from the create or connect answer: its `sandboxID`, `domain` and `trafficAccessToken`:

```bash
export SANDBOX_DOMAIN="<domain from the answer>"
export TRAFFIC_ACCESS_TOKEN="<trafficAccessToken from the answer>"

curl -sS "https://8080-$SANDBOX_ID.$SANDBOX_DOMAIN/" \
  -H "e2b-traffic-access-token: $TRAFFIC_ACCESS_TOKEN"
```

If you open a web app served from a sandbox port in a browser, do not rely on cookie isolation between sandbox host names: see [Cookies and browsers](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#cookies-and-browsers).
