Skip to main content

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). 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 APIhttps://api.serenityedge.ai, the host of the inference API. The paths are the E2B API's (below), not under /v1
Inside a sandboxhttps://<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
AuthenticationX-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 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).
  • 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).
  • Request bodies are JSON, at most 1 MiB. A larger body gets 413 edge_request_too_large.

Endpoints​

Supported​

EndpointWhat it doesNotes
POST /sandboxes, POST /v2/sandboxesCreate a sandboxOnly the create fields below. Counts against your running and creates-per-minute limits
GET /sandboxes, GET /v2/sandboxesList your sandboxesThe 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}/metricsRead sandbox metricsNot 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}/timeoutSet a new timeout, counted from nowSee Timeouts
POST /sandboxes/{sandboxID}/refreshesExtend the life of a running sandbox
POST /sandboxes/{sandboxID}/pausePause a running sandboxSee Pause and resume
POST /sandboxes/{sandboxID}/connect, POST /v2/sandboxes/{sandboxID}/connectConnect to a sandbox; resumes it when it is pausedA resume counts against your running limit. The body may not carry network fields
POST /sandboxes/{sandboxID}/resumeResume 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}/forkStart up to 100 copies of a running sandboxEach 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 templatesRead only
POST /sandboxes/{sandboxID}/snapshotsSave a sandbox as a private template of your accountOnly on accounts with templates enabled, on request; see Save a sandbox as a template
GET /snapshotsList your account's templatesAs above
DELETE /templates/{templateID}Delete one of your account's templatesAs 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.

EndpointAnswerWhy
PUT /sandboxes/{sandboxID}/network403 edge_egress_managedOutbound access is set by Serenity Edge and cannot be changed by the client (see Outbound access)
GET /sandboxes/{sandboxID}/logs, GET /v2/sandboxes/{sandboxID}/logs403 edge_logs_not_availableSandbox 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_disabledTemplate 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 enabled404 edge_route_not_availableNot part of the sandbox API on Serenity Edge
Any request that asks to switch protocols (Upgrade) on the control API400 edge_upgrade_not_supportedThe 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.

FieldRule
templateIDRequired. 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
timeoutSeconds, a non-negative integer. See Timeouts
metadataAn object of string values, at most 4,096 bytes in total (see Metadata)
envVarsAn object of string values, set as environment variables in the sandbox
autoPauseA boolean. When true, the sandbox is paused at its timeout instead of killed
autoResumeOnly {"enabled": false}. {"enabled": true} gets 400 edge_field_not_supported: a paused sandbox is resumed only by a connect or resume call
secureAlways on. false gets 400 edge_field_not_supported
cpuCount, memoryMBOptional. 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
networkOnly 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_accessOptional. 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: [] 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:

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); 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.

Size2 vCPUs, 2 GiB of memory and about 26 GiB of disk, of which 20 GiB are free when the sandbox starts
SystemUbuntu 24.04. The user is user, with the home directory /home/user and sudo without a password
Languages and build toolsPython 3.12 with pip, venv and uv; Node.js 26 (LTS) with npm; the .NET 10 SDK; gcc, g++ and make
Python librariesCommon libraries for data and science, charts, Office documents and PDF, HTML and scraping, and Google APIs; Jupyter kernels and nbconvert (no JupyterLab)
Documents and mediaLibreOffice (headless, with unoserver), pandoc, ffmpeg, ImageMagick, poppler-utils, and Tesseract OCR with English and Spanish
Command-line toolsgit, git-lfs, the GitHub CLI (gh), ripgrep, fd, jq, curl, wget
BrowserPlaywright with its Chromium headless shell (headless only)
Outbound accessThe 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, 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).
  • 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, 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.

EventResultBilling
CreaterunningRunning price from this moment
Pause, or timeout with autoPause: truepaused: memory, disk and processes are storedRunning price ends, paused price starts
Connect or resumerunning again, with memory, disk and processes as they werePaused price ends, running price starts
Kill, or timeout without autoPauseGone: memory and disk are discardedEnds
Paused for 30 daysGone: the stored memory and disk are deletedEnds at the 30 days
Platform failureGoneEnds at the failure; see 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.

ToUse, in the E2B SDKs
Run a command and read its output, or start it in the backgroundsandbox.commands.run
List the running processes, send input to one, or end itThe other methods of sandbox.commands
Read, write and list filessandbox.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 itsandbox.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.