# Sandbox network access and security

> What a Serenity Edge sandbox can reach, who can reach it, how sandboxes are isolated, what browsers keep apart, and what Serenity Edge logs and does not log about them.

Source: https://docs.serenityedge.ai/docs/sandboxes/network-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](https://docs.serenityedge.ai/docs/sandboxes/overview/#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](https://docs.serenityedge.ai/release-notes/).

## Summary

| Question | Answer |
| --- | --- |
| 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](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#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](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#cookies-and-browsers). |
| Are commands or file contents logged? | No. See [What is logged](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#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](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#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](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#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](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#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](https://publicsuffix.org/), 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](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#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](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#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.

```python
sandbox = Sandbox.create(allow_internet_access=False, timeout=300)
```

```javascript
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](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#metadata).
-   **Billing is the same.** A sandbox with no internet access is billed exactly as any other, at the same [prices](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/).

## 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:**

| What | Contents | Never in it | Kept for |
| --- | --- | --- | --- |
| Control API requests, in the sandbox service | Method, route (as a pattern, not the path), account, a short fingerprint of the key, status, latency and sandbox id | Request body, metadata, query string, client address, the API key itself | 12 months, as audit records |
| Control API requests, on the API host | As 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 agent | Request body, metadata, query string, client address, the API key itself | 90 days, as the API's request metadata (see [Data residency](https://docs.serenityedge.ai/docs/data-residency/)) |
| Outbound connections | Time, account, sandbox id, destination domain and port, whether it was allowed, bytes sent and received, duration | Path, query string, headers, body, client and destination IP addresses | 90 days |
| File operations | The paths of the files you read and write may appear in service logs | File contents | 90 days |
| Usage | Account, sandbox id, times, size, amounts and the sandbox's metadata (see [How usage is recorded](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/#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](https://docs.serenityedge.ai/terms/terms-of-service/) (Annex 1) and the [Data Processing Agreement](https://docs.serenityedge.ai/terms/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](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/#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](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#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:

|  | Host | Authentication |
| --- | --- | --- |
| Control API: create, list, pause, resume, kill | `api.serenityedge.ai`, the host of the inference API | Your 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.cloud` | The 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.
