Sandboxes
Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see Access). Limits and prices may change during the preview, and every change will be announced in the release notes. What the preview does not include is listed under Preview status.
Serenity Edge Sandboxes are isolated microVMs for AI agents: Linux machines that you create through an API. You run commands in a sandbox, read and write its files, pause it, resume it later and kill it when you are done. Sandboxes are made for code that an AI agent writes or chooses: the code runs in the sandbox, not on your servers, and each sandbox has its own kernel, memory and disk.
The API is compatible with the E2B API and SDKs. Code that already uses an official E2B SDK needs only two settings: E2B_DOMAIN set to serenityedge.ai and your Serenity Edge API key. Sandboxes are managed through the same API host as inference, with the same key.
| SDKs | The official E2B SDKs: pip install e2b for Python, npm install e2b for JavaScript. Tested with version 2.63.0 |
| Configuration | E2B_DOMAIN set to serenityedge.ai and E2B_API_KEY set to your Serenity Edge API key |
| API | https://api.serenityedge.ai, the host of the inference API, on the E2B API's paths (/sandboxes, /v2/sandboxes), which are not under /v1. Compatible with the E2B API (see API reference for the differences) |
| Authentication | Your Serenity Edge API key, the same key you use for inference, in the X-API-Key header |
| Template | One public template, used by default, so Sandbox.create() needs no arguments: Ubuntu 24.04 with tools for agents, 2 vCPUs, 2 GiB of memory and about 26 GiB of disk, of which 20 GiB are free (see Templates). On request, your account can also save a sandbox as a private template and create sandboxes from it (see Save a sandbox as a template) |
| Inside a sandbox | Commands, files and an interactive terminal through the SDKs, over HTTPS, on the sandbox's own domain, which the API returns with each sandbox (see The sandbox domain). No SSH |
| Outbound access | Public websites and APIs over HTTP and HTTPS (ports 80 and 443), through Serenity Edge's egress proxy, and nothing else. Or no internet access at all, chosen at create (see Outbound access) |
| Limits | Up to 48 running sandboxes and 60 creates per minute per account, and 8 control API requests in flight and 120 per minute per key. A sandbox runs for at most 24 hours (see Limits and quotas) |
| Prices | 0.0504 USD per vCPU-hour and 0.0162 USD per GiB-hour of memory while running, billed per second; 0.08 USD per GiB-month while paused (see Pricing and usage) |
| Pause and resume | Files, memory and running processes are kept. A paused sandbox is kept for up to 30 days |
| Location | The European Union, on Substrate AI's own hardware |
A first sandbox
With E2B_DOMAIN and E2B_API_KEY set as above, this creates a sandbox from the default template, runs a command in it and kills it:
from e2b import Sandbox
sbx = Sandbox.create()
print(sbx.commands.run("uname -a").stdout)
sbx.kill()
The quickstart sets up the SDK and goes through the whole lifecycle, in Python, JavaScript and curl.
What sandboxes are for
- Running generated code. An agent writes a script, runs it in a sandbox and reads the output, without access to your own systems.
- Tools for agents. A shell, a file system and a process list that an agent can use as tools, with the state kept between calls.
- Long tasks with breaks. Pause a sandbox while the agent waits for a person or for another system, and resume it with its memory, disk and processes as they were.
How sandboxes relate to the rest of the API
- The same key. A sandbox request is authenticated with the same Serenity Edge API key that you use for inference. The key must belong to an account that has Sandboxes enabled (see Access).
- The same API host. Sandboxes are managed through
https://api.serenityedge.ai, the host you already call for inference. Their paths are the E2B API's, such as/sandboxesand/v2/sandboxes, not the inference paths under/v1, and they take the key in theX-API-Keyheader, as the E2B SDKs send it. - Billed to the same account. Sandbox usage is billed to the account that owns the key, at the sandbox prices.
- Separate limits. The rate limits of the inference API do not apply to sandboxes, which have their own, and sandbox calls never count against the limits of inference.
The API has two parts, as the E2B API does. The SDKs use both for you:
| Part | Where | Authentication |
|---|---|---|
| Control: create, list, pause, resume, kill | https://api.serenityedge.ai, on the E2B API's paths | Your Serenity Edge API key |
| Inside a sandbox: commands, files, a terminal and ports | https://<port>-<sandbox id>.<sandbox domain>, on the sandbox domain the API returns for that sandbox | The sandbox's own access tokens, returned when you create or connect to it |
The sandbox domain
A sandbox's own traffic, its commands, files, terminal and ports, goes to the sandbox domain of the site where it runs, not to serenityedge.ai. What a sandbox serves is never served under serenityedge.ai: it stays on a domain of its own, apart from the API, the website and these docs.
You do not set the sandbox domain. The API returns it with each sandbox, in the domain field of the create and connect answers, and the SDKs use it for you: sandbox.get_host(8080) in Python and sandbox.getHost(8080) in JavaScript give the host name of a port. In the preview every sandbox runs in one site, in the European Union, and its domain is vlc1.serenitysandboxes.cloud.
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).
If you set E2B_DOMAIN to the site's domain
The preview was first set up with E2B_DOMAIN=vlc1.serenitysandboxes.cloud (see the release note of 12 November). That setting keeps working, with the same key, so nothing breaks. The documented setting is now E2B_DOMAIN=serenityedge.ai: change to it when you next update your configuration. Your code does not change.
Access
Sandboxes are a private preview, by invitation. They are enabled on request for the accounts of existing Serenity Edge customers and partners. Once they are enabled for your account, the Serenity Edge API key you already use for inference works for sandboxes too: there is no separate key. Sandboxes take Serenity Edge API keys only, the keys Substrate AI issues directly to customers and partners.
To ask for access, see Enterprise or write to contact@substrate.ai.
A Serenity Edge API key whose account does not have Sandboxes enabled gets HTTP 403 with error_code: "edge_sandboxes_not_enabled" on the sandbox paths, even though it works for inference.
Preview status
The preview is for development and evaluation. The independent security testing of the service is not finished yet, so do not put production secrets or personal data in a preview sandbox.
What the preview includes:
- creating, listing, pausing, resuming and killing sandboxes with the official E2B SDKs or over HTTP;
- running commands, working with files and opening a terminal inside a sandbox through the SDKs, over HTTPS;
- reaching a process that listens on a sandbox port, by name, with the sandbox's traffic access token;
- outbound access to public websites and APIs over HTTP and HTTPS, or no internet access at all, chosen at create;
- one public template and one sandbox size, the template's;
- on request, per account, saving a sandbox as a private template of your account and creating sandboxes from it (see Save a sandbox as a template);
- billing per second at the published prices, and each key's usage records through
GET /v1/usage.
Limitations of the preview to plan for:
- No backups yet. Paused sandboxes are not backed up during the preview. If the site's storage fails, paused sandboxes can be lost with their memory and disk. Keep anything you need outside the sandbox.
- One site. The preview runs in one site, in the European Union. There is no second site to move sandboxes to.
- Limits and prices may change during the preview. Every change will be announced in the release notes.
- CPU time is shared under load. You are billed for the vCPUs a sandbox reserves, and under load sandboxes share CPU time, as on burstable instances (see Sandbox size).
- Browsers do not keep sandbox hosts apart yet. Do not rely on cookie isolation between sandbox host names (see Cookies and browsers).
- Outbound traffic leaves from a shared address of the site, which some websites limit or block (see Outbound access).
What is not available in the preview:
| Not available in the preview | What happens instead |
|---|---|
| Desktops and computer use | Coming soon. Desktop sandboxes for computer-use agents are not available in the preview yet |
Building or changing templates, such as e2b template build | 403 edge_template_builds_disabled. Saving a sandbox as a template is available on request instead (see Save a sandbox as a template); without it, a save gets the same answer |
| Choosing the number of vCPUs or the memory of a sandbox | A size other than the template's gets 400 edge_shape_limit |
| GPUs | Sandboxes have vCPUs, memory and disk only |
| Public URLs for sandbox ports | Every request to a port needs the sandbox's traffic access token; asking for public traffic gets 403 edge_public_traffic_not_supported |
| Setting outbound network rules from the client | Outbound access is set by Serenity Edge, the same for every account; the only client choice is no internet access at create, and other settings, such as network.allowOut, get 403 edge_egress_managed |
| Outbound connections other than HTTP and HTTPS, such as SSH or git over SSH | Dropped. Use HTTPS (see Outbound access) |
| SSH into a sandbox | Use the SDKs' commands and terminal (see Running commands and opening a terminal) |
| Credentials added to a sandbox's outbound requests by Serenity Edge, so that a secret never enters the sandbox | Not offered in the preview. Code that calls an authenticated API needs its own credential: give it the least access and the shortest life the task allows, never your Serenity Edge API key |
Sandbox logs (GET /sandboxes/{sandboxID}/logs) | 403 edge_logs_not_available. Capture the output of your commands in your client |
Sandbox metrics (get_metrics in the SDKs, the metrics routes) | An empty list, or HTTP 400 when a start time is given; see Known issues in the preview |
Create fields outside the supported list, such as volume mounts or secure: false | 400 edge_field_not_supported (see Create fields) |
| Volumes, secrets and the other routes outside the sandbox lifecycle | 404 edge_route_not_available |
| Idempotent creates | A create sent twice makes two sandboxes; see Retrying a create |
| A spending cap | Not offered in the preview; use the timeout of each sandbox and your account's limits |
| A webhook that sends your usage records | Not offered in the preview; read them with GET /v1/usage (see Check your usage) |
| A service level | A sandbox lost to a platform failure is not billed after the failure; there is no credit |
| A published range of supported SDK versions | The preview is tested with the E2B SDK e2b 2.63.0 |
Known issues in the preview
These issues were found while testing the preview with the E2B SDK e2b 2.63.0. Each fix will be announced in the release notes.
| Issue | What happens | What to do |
|---|---|---|
Writing a file again under /tmp | Writing a file with sandbox.files.write to a path under /tmp that was already written fails with HTTP 500 and "permission denied". Writing the same path again under the home directory works. | Write files under the home directory, /home/user. A fix is coming. |
| Sandbox metrics | Sandbox metrics are not available in the preview. get_metrics in the SDKs and GET /sandboxes/{sandboxID}/metrics return an empty list, and a request with a start time gets HTTP 400. | Do not rely on sandbox metrics during the preview. |
| Deleting a template by its snapshot id | Deleting one of your templates by the snapshot id that the SDKs return, <your account>/<name>:<tag>, gets HTTP 404 with edge_route_not_available, and delete_snapshot returns False: the template is not deleted. | Delete by the bare name, without your account's namespace, such as Sandbox.delete_snapshot("data-env") (see Save a sandbox as a template). The fix will be announced in the release notes. |
Next steps
- Quickstart: install the SDK, create a sandbox, run a command, pause, resume and kill.
- API reference: the supported endpoints and fields, the template, and what differs from E2B.
- Save a sandbox as a template: your own templates, on request.
- Errors, Limits and quotas, Pricing and usage and Network access and security.