> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking and egress

> What a sandbox can reach, and who can reach it.

## Egress

Every create compiles a network policy from three layers, strictest first:

1. **The platform floor**, which no setting can open: private and internal ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, loopback, link-local including the cloud metadata address `169.254.169.254`, multicast and reserved ranges, and their IPv6 equivalents), names such as `localhost`, `*.local` and `*.internal`, and the mail and DNS-over-TLS ports 25, 465, 587, 2525 and 853. Those ports are blocked for TCP and UDP to every destination, and the packets are dropped rather than refused, so a connection attempt to one of them times out.
2. **Your plan's limits.** Paid plans allow the public internet by default; the free plan allows no public egress for now. **Coming soon:** Free egress on, capped at its included 5 GB a month (see [limits](/docs/concepts/limits.md)).
3. **The sandbox's own policy**: the E2B fields below on create, else your team's egress settings (see [Which policy applies](#which-policy-applies)).

| Field | Meaning |
| - | - |
| `allow_internet_access` | `false` cuts all public egress for this sandbox |
| `network.deny_out` | Block these IPv4 addresses or CIDRs. `0.0.0.0/0` blocks all public egress, the same as `allow_internet_access=false` |
| `network.allow_out` | Allow these destinations (IPs, CIDRs or host names) even when the rest is blocked. Allow entries win over deny entries |
| `network.allow_public_traffic` | Whether the sandbox's ports are reachable without a token (see [Ingress](#ingress)) |

```python egress.py
from anona_compute import Sandbox

offline = Sandbox.create("base", allow_internet_access=False)
offline.kill()

only_pypi = Sandbox.create(
    "base",
    network={"deny_out": ["0.0.0.0/0"], "allow_out": ["pypi.org", "files.pythonhosted.org"]},
)
only_pypi.kill()

no_example = Sandbox.create("base", network={"deny_out": ["93.184.215.14/32"]})
no_example.kill()
```

```typescript egress.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const offline = await Sandbox.create("base", { allowInternetAccess: false });
await offline.kill();

const onlyPypi = await Sandbox.create("base", {
  network: { denyOut: ["0.0.0.0/0"], allowOut: ["pypi.org", "files.pythonhosted.org"] },
});
await onlyPypi.kill();
```

```bash egress.sh
anona-compute run --no-internet -t base -- 'echo this sandbox has no internet'
```

Rules the gateway enforces when it compiles your policy:

* A destination inside the platform floor is refused with `400`, and so is a host name that resolves into it (this blocks DNS-rebinding tricks).
* Host names in `allow_out` need public egress off (`deny_out: ["0.0.0.0/0"]` or `allow_internet_access=false`), as on E2B. Wildcard names and names that do not resolve are refused for now.
* `deny_out` takes IPv4 addresses and CIDRs only.
* Unknown keys inside `network` are refused, so a typo cannot silently drop part of a policy.
* Per plan: up to 512 allow entries and 1,024 deny entries on paid plans (64 and 256 on the free plan), and at most 10 DNS servers.
* On the free plan, which has no public egress, `allow_out` opens particular hosts, not the internet: an IP range there can be at most a `/24`, and the addresses and ranges together can cover at most 1,024 addresses. Host names are not limited by this. A policy over either limit is refused with `400`.

## Which policy applies

A new sandbox gets the first of these that exists, then the platform floor and your plan's limits on top:

1. The `network` and `allow_internet_access` fields of its create request.
2. Its template's policy (built-in templates have none).
3. Your organization's **team egress settings**: set them on the dashboard's **Network** page (owners and admins), or with `PUT /v1/network`.
4. Your plan's default.

Ask the API which policy a sandbox runs with, and where it came from:

```bash effective_policy.sh
curl -sS "https://api.compute.anonalabs.com/v1/sandboxes/$SANDBOX_ID/network/effective" \
  -H "X-API-Key: $ANONA_API_KEY" | jq '{source, tier, internet: .policy.allow_internet_access}'
curl -sS https://api.compute.anonalabs.com/v1/network -H "X-API-Key: $ANONA_API_KEY" | jq '{tier, revision, limits}'
```

## Change a running sandbox

`update_network` replaces a running sandbox's policy. It goes through the same floor and limits as a create. An update that does not mention `allow_internet_access` keeps the sandbox's current setting.

```python update_network.py
from anona_compute import Sandbox

with Sandbox.create("base") as sbx:
    # lock it down to one API after setup
    sbx.update_network({"deny_out": ["0.0.0.0/0"], "allow_out": ["1.1.1.1"]})
```

```typescript update_network.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base");
await sbx.updateNetwork({ denyOut: ["0.0.0.0/0"], allowOut: ["1.1.1.1"] });
await sbx.kill();
```

The caller needs to be able to control the sandbox: an API key with `sandboxes:use` (and the sandbox on its list, if it has one), or a dashboard member or above.

## Credentials without exposing them

The **credential vault** keeps API tokens out of sandboxes. Store a secret, with the hosts it may be sent to, on the dashboard's **Credential vault** page (owners and admins) or with `anona-compute vault create`. Then name it in a header rule for one host; creating a sandbox with a new rule takes the permission in [Bindings and who can make them](#bindings-and-who-can-make-them). The egress proxy adds the header to the sandbox's HTTPS requests to that host; the sandbox, its environment and its disk never contain the value.

```python vault_rule.py
from anona_compute import Sandbox

# "github_token" was stored in the dashboard's Credential vault first.
sbx = Sandbox.create(
    "base",
    network={
        "deny_out": ["0.0.0.0/0"],
        "allow_out": ["api.github.com"],
        "rules": {"api.github.com": [{"transform": {"headers": {"Authorization": "Bearer ${vault.github_token}"}}}]},
    },
)
print(sbx.commands.run("env | grep -ci token || true").stdout.strip(), "token variables in the sandbox")
sbx.kill()
```

```typescript vault_rule.ts
import { Sandbox } from "@anona-labs/compute-sdk";

const sbx = await Sandbox.create("base", {
  network: {
    denyOut: ["0.0.0.0/0"],
    allowOut: ["api.github.com"],
    rules: { "api.github.com": [{ transform: { headers: { Authorization: "Bearer ${vault.github_token}" } } }] },
  },
});
await sbx.kill();
```

* A header value must be exactly one `${vault.<name>}`, optionally after `Bearer ` or `Basic `. A literal value is refused with `400`, so no credential ends up in a policy. So is a rule with an empty `headers` object.
* Each rule names one exact host. A wildcard such as `*.example.com` is refused with `400`.
* Proxies cache a value for up to 60 seconds, so a rotation or revocation reaches running sandboxes within a minute.
* The same rules work in the team egress settings, so every new sandbox gets them.
* Secret names start with a lowercase letter, then lowercase letters, digits and `_`, up to 63 characters in all; values up to 8 KiB.

From the CLI, the same thing without writing the rule by hand:

```bash vault_cli.sh
# The value comes from a file or a pipe, never an argument: an argument is in
# your shell history and in the process table.
anona-compute vault create github_token --host api.github.com --value-file token.txt

anona-compute create --no-internet \
  --allow-out api.github.com \
  --vault-inject api.github.com:Authorization=bearer:github_token

anona-compute vault list          # names, allowed hosts and bindings; never a value
anona-compute vault rotate github_token --value-file new-token.txt
```

There is no `vault get`: no response from the API carries a value, so the CLI has nothing to print.

The vault is included in every plan at no charge.

### Allowed hosts

Every secret records the hosts it may be sent to. You set them when you store it (`--host` on the CLI, `allowedHosts` in the API), and replace them with `anona-compute vault allowed-hosts` or `PUT /v1/vault/secrets/{name}/allowed-hosts`. An entry is one of:

* an exact host: `api.github.com` covers that host only;
* `*.` and a domain: `*.github.com` covers every host under `github.com`, but not `github.com` itself. So `*.httpbin.org` does not cover `httpbin.org`; list both if you need both;
* `*` on its own, for any host.

The list cannot be empty: storing a secret without one is refused with `400`. A rule that sends the secret to a host outside the list is refused with `403`. Narrowing the list also stops existing bindings to hosts it no longer covers. Without the list, anyone who can write a rule could point your credential at a server they control.

### Bindings and who can make them

A rule needs a **binding**: a record that this secret goes to this host in this header. The vault page and `anona-compute vault list` show every binding, and each can be revoked.

* A rule in a sandbox's create request, or in a network update, is bound for that sandbox alone. Two sandboxes with the same secret, host and header have two bindings, each listed with scope `sandbox` and its sandbox ID.
* A rule in the team egress settings or a template's policy is bound once, when the settings are saved, and every sandbox under them uses that binding.
* A sandbox's own bindings are revoked when the sandbox ends (deleted, timed out or failed), so they drop out of the list. A paused sandbox keeps its bindings, because it can resume. Team and template bindings stay until you revoke them or delete the secret.

Making a new binding takes permission to aim a secret at a host. An organization owner or admin has it, signed in on the dashboard or with `anona-compute login`. So does an API key with the `vault:bind` scope that is not limited to specific sandboxes, and an unrestricted API key (no scopes and no sandbox list, see [API keys](/docs/guides/ci.md#create-a-key-for-ci)). No preset has `vault:bind`, not even **Full access**: pick it in a custom key.

Anyone else who can create sandboxes can still use the rules in the team egress settings and templates, because those bindings exist already. Any other rule in their create request or network update is refused with `403`, even when another sandbox has the same rule: a sandbox's binding is not shared.

### How it works

For a host with a vault rule, the egress proxy ends the sandbox's TLS connection and opens its own to the host, which it verifies. So the sandbox sees a certificate for that host issued by the egress proxy's certificate authority, valid for about 7 days. That certificate authority is in the sandbox's system bundle, `/etc/ssl/certs/ca-certificates.crt`, and `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` (also `PIP_CERT` and `GIT_SSL_CAINFO`) point at that file. curl, Python's default SSL context and Node accept the certificate.

A client with its own certificate store fails the handshake with a certificate error: Python with certifi's bundle passed explicitly, a Java keystore, or a pinned certificate. Point it at `/etc/ssl/certs/ca-certificates.crt`, or call the host from a client that uses the system bundle.

Each rule shows `"audit": "metadata"` in the sandbox's compiled policy. For every request it matches, the egress proxy records the time, method, host, path, response status and size, the rule, and the names of the headers it added. It does not record request or response bodies.

## Ingress

All traffic to a sandbox goes through the Anona gateway at `https://<port>-<sandbox id>.sbx.compute.anonalabs.com`:

| Port | Who gets in |
| - | - |
| 49983 (`envd`: commands, files) | Only requests with the sandbox's access token, which the SDK holds; signed file URLs for `GET`/`POST /files` |
| Any other port | Anyone, when the sandbox allows public traffic or the port is public; otherwise a valid preview link (or its cookie), or the `e2b-traffic-access-token` header |

Single ports can also be made public, or shared with signed, expiring links; see [Preview links](/docs/guides/preview-links.md). Sandbox URLs live on their own domain, so content served from a sandbox never shares cookies with the API or the dashboard.

## DNS

Sandboxes resolve names through public resolvers (1.1.1.1 and 1.0.0.1), so they cannot resolve names inside Anona's network. Both are always allowed, whatever the policy. A policy's `dnsServers` does not change them: another address listed there is only allowed as a destination, when `allow_out` has a host name and public egress is off. The free plan accepts only these two.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.