Skip to main content

Sandbox network access and security

Private preview

Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see Access). The independent security testing of the service is not finished yet, so do not put production secrets or personal data in a preview sandbox. Changes will be announced in the release notes.

Summary​

QuestionAnswer
What isolates a sandbox?Each sandbox is its own microVM, with its own kernel, memory and disk.
Who can manage a sandbox?Only the account that created it, with its API key.
Who can reach a sandbox's ports?Only a caller with that sandbox's traffic access token. Public URLs are not available in the preview.
What can a sandbox reach?Public websites and APIs, over HTTP (port 80) and HTTPS (port 443), through Serenity Edge's egress proxy, with shared, capped bandwidth. Nothing else. A sandbox created without internet access reaches nothing at all.
Can I SSH into a sandbox?No. Use the SDKs' commands and terminal (PTY): see Running commands and opening a terminal.
Can a sandbox use git over SSH?No. Outbound SSH is blocked: clone and push over HTTPS.
Do browsers keep sandbox host names apart?Not yet. Do not rely on cookie isolation between them: see Cookies and browsers.
Are commands or file contents logged?No. See What is logged.
Is a sandbox's content served under serenityedge.ai?No. The API is at api.serenityedge.ai, but what a sandbox serves stays on its sandbox domain: see Hosts and domains.
Where do sandboxes run?In the European Union, on Substrate AI's own hardware.

Isolation​

  • One microVM per sandbox. A sandbox does not share a kernel, memory or disk with any other sandbox, of your account or of another.
  • Your account only. The control API acts on a sandbox only for the account that created it. A call with another account's key gets HTTP 404, as for a sandbox that does not exist.
  • Tokens per sandbox. Commands and files inside a sandbox need that sandbox's access token (envdAccessToken), and its ports need its traffic access token (trafficAccessToken). Both come in the create and connect answers. This protection cannot be turned off: a create with secure: false is refused with 400 edge_field_not_supported.
  • Your API key stays outside. Nothing in a sandbox needs your Serenity Edge API key. Do not pass it in through envVars, files or commands: code that runs in the sandbox could read it.

Inbound access​

A process that listens on a port in a sandbox is reachable by name at https://<port>-<sandbox id>.<sandbox domain>, on the sandbox domain the API returns for it, and only with the sandbox's traffic access token in the e2b-traffic-access-token header. A request without the token is refused (see Sandbox ports).

There is no SSH access. Commands, files and a terminal go through the SDKs over HTTPS, with the sandbox's access token (see Running commands and opening a terminal).

Public sandbox URLs are not available in the preview: a create with network.allowPublicTraffic: true gets 403 edge_public_traffic_not_supported.

Cookies and browsers​

Until serenitysandboxes.cloud is on the Public Suffix List, do not rely on cookie isolation between sandbox host names. A browser treats every host name under serenitysandboxes.cloud, such as <port>-<sandbox id>.vlc1.serenitysandboxes.cloud, as one site:

  • a page served by any sandbox, yours or another account's, can set a cookie for the whole sandbox domain, and the browser then sends that cookie to every other sandbox host;
  • SameSite protections do not separate one sandbox host from another.

This matters only when a person opens a web app served from a sandbox port in a browser. The sandbox API itself takes your key and the sandbox's tokens in headers and sets no cookies. If you serve a web app from a sandbox, do not keep sessions or other secrets in cookies, and treat any cookie the app receives as set by someone else.

Outbound access​

In the preview, a sandbox can reach public websites and APIs over HTTP (port 80) and HTTPS (port 443), through Serenity Edge's egress proxy. Nothing else leaves a sandbox. Outbound access is the same for every account. The one choice you have is to create a sandbox with no internet access at all (see Sandboxes with no internet access).

Set up in the template. The template sets the proxy in the HTTP_PROXY and HTTPS_PROXY environment variables (with NO_PROXY) and in the configuration of the usual tools, and points DNS at Serenity Edge's resolver, so tools that read the standard proxy settings work with no configuration: pip, uv, npm, curl, wget, apt, gh, dotnet and git over HTTPS among them. A program that ignores those settings and connects directly reaches nothing. Give such a program the proxy in HTTPS_PROXY explicitly.

What a sandbox can reach: public destinations, by name or by address, on ports 80 and 443, through the proxy. DNS works, through Serenity Edge's resolver.

What it cannot reach:

  • any other port, SSH (22) and mail (SMTP: 25, 465, 587 and 2525) included. git over SSH does not work: use HTTPS remotes instead;
  • anything without the proxy: direct connections are dropped;
  • UDP and QUIC, other than DNS to the sandbox's resolver (HTTP/3 clients fall back to TCP);
  • IPv6;
  • private and internal address ranges: private networks, shared and reserved ranges, loopback and link-local addresses, and cloud metadata addresses, whether given as an address or as a name that resolves to one;
  • Serenity Edge's own addresses.

How it is enforced. Outbound traffic leaves a sandbox only through Serenity Edge's egress proxy and DNS filter:

  • HTTP and HTTPS go through the proxy, which checks the port and connects only to public addresses.
  • On port 443 the connection must be TLS, and the server name it asks for must be the destination given to the proxy.
  • DNS goes only to the sandbox's resolver. Queries to any other resolver are dropped.
  • Everything else is dropped.

Bandwidth. Outbound traffic has shared, capped bandwidth, divided fairly between the sandboxes that use it at the same time. A large download can be slower when other sandboxes are busy.

Your sandbox's outbound address. Outbound connections leave from a shared address of the site, not from one of your own. It is not published and may change, so do not add it to an allow list at a destination. Some websites limit or block shared addresses.

A client cannot widen or change any of this. Apart from turning internet access off at create, every outbound network setting in a request is refused with 403 edge_egress_managed: network.allowOut, denyOut, dnsServers, rules and egressProxy on create, allow_internet_access: true, any network field on fork, resume or connect, and PUT /sandboxes/{sandboxID}/network.

Every outbound connection is recorded with its sandbox and account, never its content (see What is logged).

Credentials for outbound calls are yours to provide: Serenity Edge does not add credentials to a sandbox's outbound requests in the preview. If code in a sandbox must call an authenticated API, give it a credential with the least access and the shortest life the task allows, never your Serenity Edge API key.

Sandboxes with no internet access​

Create a sandbox with allow_internet_access: false and nothing leaves it: the egress proxy refuses every request from it, and its resolver answers no query. Use it for code that must not send data anywhere.

sandbox = Sandbox.create(allow_internet_access=False, timeout=300)
const sandbox = await Sandbox.create({ allowInternetAccess: false, timeoutMs: 300_000 });
  • Only outbound traffic is cut. Commands, files, the terminal and the sandbox's ports work as for any other sandbox, through the SDKs and with the sandbox's tokens.
  • Nothing can be downloaded from inside it. pip install, npm install, git clone and any other call to the internet fail. Upload what the code needs through the SDKs' file methods.
  • The choice is made at create. No later request turns internet access on or off for an existing sandbox.
  • Metadata. Serenity Edge adds the key edge.egress with the value off to the sandbox's metadata. It comes back when you read or list the sandbox, and it counts toward the 4,096-byte limit of metadata.
  • Billing is the same. A sandbox with no internet access is billed exactly as any other, at the same prices.

What is logged​

A sandbox holds your data while it exists: that is its purpose. What Serenity Edge commits to is that the content of your work is not written to its logs, and that a sandbox's data is deleted after the sandbox ends.

Not logged:

  • the commands you run and their arguments;
  • environment variables;
  • what you send to a process's standard input;
  • the contents of files.

Logged:

WhatContentsNever in itKept for
Control API requests, in the sandbox serviceMethod, route (as a pattern, not the path), account, a short fingerprint of the key, status, latency and sandbox idRequest body, metadata, query string, client address, the API key itself12 months, as audit records
Control API requests, on the API hostAs for inference requests: method, path (which holds the sandbox id), account, a short fingerprint of the key, status, latency, request and answer sizes and the client's user agentRequest body, metadata, query string, client address, the API key itself90 days, as the API's request metadata (see Data residency)
Outbound connectionsTime, account, sandbox id, destination domain and port, whether it was allowed, bytes sent and received, durationPath, query string, headers, body, client and destination IP addresses90 days
File operationsThe paths of the files you read and write may appear in service logsFile contents90 days
UsageAccount, sandbox id, times, size, amounts and the sandbox's metadata (see How usage is recorded)For the term of your agreement, then as long as commercial, accounting and tax law require

These periods are the ones of the Terms of Service (Annex 1) and the Data Processing Agreement (Exhibit 4), which are binding.

Metadata is stored with the sandbox and copied into your usage records; it is not written to the request logs. Do not put secrets or personal data in metadata or in file paths.

Stored:

  • While a sandbox is paused, its memory and disk are stored so that it can be resumed.
  • After a kill or an expiry, the sandbox's stored memory and disk are deleted in a periodic clean-up. See Data lifetime.

Sandbox logs are not available in the preview (403 edge_logs_not_available).

Good practice​

  • Treat the code that runs in a sandbox as untrusted, including code your own agent wrote.
  • Give a sandbox only the data its task needs, and copy results out before you kill it.
  • Fetch code and packages over HTTPS. SSH and ports other than 80 and 443 are not available from a sandbox.
  • Do not keep sessions or secrets in cookies of a web app served from a sandbox (see Cookies and browsers).
  • Set a timeout on every sandbox, and kill paused sandboxes you no longer need.

Hosts and domains​

A client of Sandboxes talks to two kinds of host:

HostAuthentication
Control API: create, list, pause, resume, killapi.serenityedge.ai, the host of the inference APIYour Serenity Edge API key
Inside a sandbox: commands, files, a terminal and ports<port>-<sandbox id>.<sandbox domain>; in the preview the sandbox domain is vlc1.serenitysandboxes.cloudThe sandbox's own tokens
  • Sandbox content stays off serenityedge.ai. What a sandbox serves, on its ports, is never served under serenityedge.ai. It stays under serenitysandboxes.cloud, a domain of its own, so it cannot set or read cookies of the API, the website or these docs.
  • The API tells the SDKs where a sandbox is. The create and connect answers carry the sandbox domain in their domain field, and the SDKs send that sandbox's traffic there. You do not set it.
  • What to allow. Outbound HTTPS to api.serenityedge.ai and to the sandbox domain and its subdomains (*.vlc1.serenitysandboxes.cloud in the preview). Nothing else, and no SSH.