Skip to main content

Sandboxes

Private preview

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.

SDKsThe official E2B SDKs: pip install e2b for Python, npm install e2b for JavaScript. Tested with version 2.63.0
ConfigurationE2B_DOMAIN set to serenityedge.ai and E2B_API_KEY set to your Serenity Edge API key
APIhttps://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)
AuthenticationYour Serenity Edge API key, the same key you use for inference, in the X-API-Key header
TemplateOne 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 sandboxCommands, 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 accessPublic 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)
LimitsUp 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)
Prices0.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 resumeFiles, memory and running processes are kept. A paused sandbox is kept for up to 30 days
LocationThe 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 /sandboxes and /v2/sandboxes, not the inference paths under /v1, and they take the key in the X-API-Key header, 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:

PartWhereAuthentication
Control: create, list, pause, resume, killhttps://api.serenityedge.ai, on the E2B API's pathsYour Serenity Edge API key
Inside a sandbox: commands, files, a terminal and portshttps://<port>-<sandbox id>.<sandbox domain>, on the sandbox domain the API returns for that sandboxThe 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 [email protected].

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 previewWhat happens instead
Desktops and computer useComing soon. Desktop sandboxes for computer-use agents are not available in the preview yet
Building or changing templates, such as e2b template build403 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 sandboxA size other than the template's gets 400 edge_shape_limit
GPUsSandboxes have vCPUs, memory and disk only
Public URLs for sandbox portsEvery 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 clientOutbound 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 SSHDropped. Use HTTPS (see Outbound access)
SSH into a sandboxUse 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 sandboxNot 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: false400 edge_field_not_supported (see Create fields)
Volumes, secrets and the other routes outside the sandbox lifecycle404 edge_route_not_available
Idempotent createsA create sent twice makes two sandboxes; see Retrying a create
A spending capNot offered in the preview; use the timeout of each sandbox and your account's limits
A webhook that sends your usage recordsNot offered in the preview; read them with GET /v1/usage (see Check your usage)
A service levelA sandbox lost to a platform failure is not billed after the failure; there is no credit
A published range of supported SDK versionsThe 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.

IssueWhat happensWhat to do
Writing a file again under /tmpWriting 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 metricsSandbox 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 idDeleting 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​