Sandboxes API reference
Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see 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.
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.
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), 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).
Authorization: Bearer <key>is also accepted whenX-API-Keyis 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 witherror_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).
- 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,
envdAccessTokenandtrafficAccessToken, which the create and connect answers return withdomain. The SDKs handle the calls for commands, files and a terminal for you (see 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 below. Counts against your running and creates-per-minute limits |
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) |
POST /sandboxes/{sandboxID}/timeout | Set a new timeout, counted from now | See Timeouts |
POST /sandboxes/{sandboxID}/refreshes | Extend the life of a running sandbox | |
POST /sandboxes/{sandboxID}/pause | Pause a running sandbox | See 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 |
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) |
The routes that the preview's tests cover end to end are create, list, pause, connect and kill, the calls of the 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) |
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 |
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). Another template gets 403 edge_template_not_allowed |
timeout | Seconds, a non-negative integer. See Timeouts |
metadata | An object of string values, at most 4,096 bytes in total (see 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). 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: []andautoPauseMemory: true. Any other value of those fields is refused with400 edge_field_not_supported,autoPauseMemory: falseincluded. - 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:
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.oredge., in any letter case, are reserved and get403 edge_metadata_reserved. Serenity Edge may add keys of its own that start withedge.(for exampleedge.egresson a sandbox 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:
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) |
- 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,pypdfium2or LibreOffice for PDF. Thevim,nanoandnetcatprograms are not installed either. - Installing packages.
pip installoutside a virtual environment installs into~/.local; useuv venvfor a project.npm install -ginstalls into~/.npm-global. Runsudo apt-get updatebeforesudo apt-get install: the package lists are not in the template. - Versions. The file
/etc/edge-template-releasein a sandbox names the template's release and its main versions. - Licences. The GPL programs in the template, such as
pandoc,poppler-utilsandffmpeg, are Ubuntu's own packages, unmodified. Their source is in Ubuntu's archive, and each package's licence is in/usr/share/doc/<package>/copyrightin 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). - The template may change during the preview, for example when its tools are updated. Changes will be announced in the 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,memoryMBanddiskSizeMBfromGET /sandboxes/{sandboxID}.diskSizeMBis 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 |
Timeouts
timeoutis the number of seconds after which a running sandbox ends. It is counted from the call that sets it: the create, a connect, orPOST /sandboxes/{sandboxID}/timeout, which replaces the previous value.- At the timeout the sandbox is killed. With
autoPause: trueon create, it is paused instead. - When you leave
timeoutout, 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 (
autoResumecannot 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_limitwithRetry-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) |
| 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. 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:
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:
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:
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.