Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 48 additions & 99 deletions docs/sandbox/internet-access.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## Controlling internet access

You can control whether a sandbox has access to the internet by using the `allowInternetAccess` parameter when creating a sandbox. By default, internet access is enabled (`true`), but you can disable it for security-sensitive workloads.
You can control whether a sandbox has access to the internet by using the `allowInternetAccess` / `allow_internet_access` parameter when creating a sandbox. By default, internet access is enabled, but you can disable it for security-sensitive workloads.

<CodeGroup>
```js JavaScript & TypeScript
Expand All @@ -16,7 +16,7 @@
const sandbox = await Sandbox.create({ allowInternetAccess: true })

// Create sandbox without internet access
const isolatedSandbox = await Sandbox.create({ allowInternetAccess: false })

Check warning on line 19 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L19

Did you really mean 'isolatedSandbox'?
```
```python Python
from e2b import Sandbox
Expand All @@ -32,43 +32,43 @@
When internet access is disabled, the sandbox cannot make outbound network connections, which provides an additional layer of security for sensitive code execution.

<Note>
Setting `allowInternetAccess` to `false` is equivalent to setting `network.denyOut` to `['0.0.0.0/0']` (denying all traffic).
Setting `allowInternetAccess` / `allow_internet_access` to a falsy value is equivalent to setting `network.denyOut` / `network.deny_out` to `['0.0.0.0/0']` (denying all traffic).

Check warning on line 35 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L35

Did you really mean 'falsy'?
</Note>

## Fine-grained network control

For more granular control over network access, you can use the `network` configuration option to specify allow and deny lists for outbound traffic.
For more granular control over network access, you can use the network configuration option to specify allow and deny lists for outbound traffic.

### Allow and deny lists

You can specify IP addresses, CIDR blocks, or domain names that the sandbox is allowed to use:

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

// Deny all traffic except specific IPs

Check warning on line 50 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L50

Did you really mean 'IPs'?
const sandbox = await Sandbox.create({
network: {
denyOut: [ALL_TRAFFIC],
denyOut: ({ allTraffic }) => [allTraffic], // allTraffic === '0.0.0.0/0'

Check warning on line 53 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L53

Did you really mean 'allTraffic'?

Check warning on line 53 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L53

Did you really mean 'allTraffic'?
allowOut: ['1.1.1.1', '8.8.8.0/24']

Check warning on line 54 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L54

Did you really mean 'allowOut'?
}
})

// Deny specific IPs only

Check warning on line 58 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L58

Did you really mean 'IPs'?
const restrictedSandbox = await Sandbox.create({

Check warning on line 59 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L59

Did you really mean 'restrictedSandbox'?
network: {
denyOut: ['8.8.8.8']

Check warning on line 61 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L61

Did you really mean 'denyOut'?
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

# Deny all traffic except specific IPs
sandbox = Sandbox.create(
network={
"deny_out": [ALL_TRAFFIC],
"deny_out": lambda ctx: [ctx.all_traffic], # ctx.all_traffic == "0.0.0.0/0"
"allow_out": ["1.1.1.1", "8.8.8.0/24"]
}
)
Expand All @@ -82,61 +82,65 @@
```
</CodeGroup>

<Note>
The selector callback (`({ allTraffic }) => [allTraffic]` / `lambda ctx: [ctx.all_traffic]`) is the recommended way to express "all traffic" (`0.0.0.0/0`). The `ALL_TRAFFIC` constant remains exported for backward compatibility.
</Note>

### Domain-based filtering

You can allow traffic to specific domains by specifying hostnames in `allow out`. When using domain-based filtering, you must include `ALL_TRAFFIC` in `deny out` to block all other traffic. Domains are not supported in the `deny out` list.
You can allow traffic to specific domains by specifying hostnames in `allowOut` / `allow_out`. When using domain-based filtering, you must deny all other traffic in `denyOut` / `deny_out`. Domains are not supported in the deny lists.

Check warning on line 91 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L91

Did you really mean 'hostnames'?

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

// Allow only traffic to google.com
const sandbox = await Sandbox.create({
network: {
allowOut: ['google.com'],

Check warning on line 100 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L100

Did you really mean 'allowOut'?
denyOut: [ALL_TRAFFIC]
denyOut: ({ allTraffic }) => [allTraffic]
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

# Allow only traffic to google.com
sandbox = Sandbox.create(
network={
"allow_out": ["google.com"],
"deny_out": [ALL_TRAFFIC]
"deny_out": lambda ctx: [ctx.all_traffic]
}
)
```
</CodeGroup>

<Note>
When any domain is used, the default nameserver `8.8.8.8` is automatically allowed to ensure proper DNS resolution.

Check warning on line 119 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L119

Did you really mean 'nameserver'?
</Note>

You can also use wildcards to allow all subdomains of a domain:

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

// Allow traffic to any subdomain of mydomain.com
const sandbox = await Sandbox.create({
network: {
allowOut: ['*.mydomain.com'],

Check warning on line 131 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L131

Did you really mean 'allowOut'?
denyOut: [ALL_TRAFFIC]
denyOut: ({ allTraffic }) => [allTraffic]
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

# Allow traffic to any subdomain of mydomain.com
sandbox = Sandbox.create(
network={
"allow_out": ["*.mydomain.com"],
"deny_out": [ALL_TRAFFIC]
"deny_out": lambda ctx: [ctx.all_traffic]
}
)
```
Expand All @@ -146,24 +150,24 @@

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

// Allow traffic to specific domains and IPs

Check warning on line 155 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L155

Did you really mean 'IPs'?
const sandbox = await Sandbox.create({
network: {
allowOut: ['api.example.com', '*.github.com', '8.8.8.8'],
denyOut: [ALL_TRAFFIC]
denyOut: ({ allTraffic }) => [allTraffic]
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

# Allow traffic to specific domains and IPs
sandbox = Sandbox.create(
network={
"allow_out": ["api.example.com", "*.github.com", "8.8.8.8"],
"deny_out": [ALL_TRAFFIC]
"deny_out": lambda ctx: [ctx.all_traffic]
}
)
```
Expand All @@ -175,68 +179,41 @@

### Priority rules

When both `allow out` and `deny out` are specified, **allow rules always take precedence** over deny rules. This means if an IP address is in both lists, it will be allowed.
When both allow and deny rules are specified, **allow rules always take precedence** over deny rules. This means if an IP address is in both lists, it will be allowed.

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

// Even though ALL_TRAFFIC is denied, 1.1.1.1 and 8.8.8.8 are explicitly allowed
// Even though all traffic is denied, 1.1.1.1 and 8.8.8.8 are explicitly allowed
const sandbox = await Sandbox.create({
network: {
denyOut: [ALL_TRAFFIC],
denyOut: ({ allTraffic }) => [allTraffic],
allowOut: ['1.1.1.1', '8.8.8.8']
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

# Even though ALL_TRAFFIC is denied, 1.1.1.1 and 8.8.8.8 are explicitly allowed
# Even though all traffic is denied, 1.1.1.1 and 8.8.8.8 are explicitly allowed
sandbox = Sandbox.create(
network={
"deny_out": [ALL_TRAFFIC],
"deny_out": lambda ctx: [ctx.all_traffic],
"allow_out": ["1.1.1.1", "8.8.8.8"]
}
)
```
</CodeGroup>

### ALL_TRAFFIC helper

The `ALL_TRAFFIC` constant represents the CIDR range `0.0.0.0/0`, which matches all IP addresses. Use it to easily deny or allow all network traffic:

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'

// Deny all outbound traffic
const sandbox = await Sandbox.create({
network: {
denyOut: [ALL_TRAFFIC]
}
})
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC

# Deny all outbound traffic
sandbox = Sandbox.create(
network={
"deny_out": [ALL_TRAFFIC]
}
)
```
</CodeGroup>

### Per-host request transforms

<Note>
Per-host request transforms are currently in private beta.
If you'd like access, please reach out to us at [support@e2b.dev](mailto:support@e2b.dev).
</Note>

You can register per-host rules under `network.rules` to apply transforms (for example, inject HTTP headers) on outbound requests matching a host. Rules are keyed by host and registering one does **not** grant egress on its own — the host must still be referenced via `allowOut`.
You can register per-host rules under `network.rules` to apply transforms (for example, inject HTTP headers) on outbound requests matching a host. Rules are keyed by host and registering one does **not** grant egress on its own — the host must still be referenced via `allowOut` / `allow_out`.

The `transform.headers` object is sent on the wire as-is and injected by the egress proxy on matching HTTP/HTTPS requests.

Expand All @@ -248,6 +225,9 @@
network: {
// Only allow egress to hosts that have rules registered.
allowOut: ({ rules }) => [...rules.keys()],
// Deny all other traffic
denyOut: ({ allTraffic }) => [allTraffic],
// Register per-host rules
rules: {
'api.example.com': [
{
Expand All @@ -265,7 +245,11 @@

sandbox = Sandbox.create(
network={
# Only allow egress to hosts that have rules registered.
"allow_out": lambda ctx: list(ctx.rules.keys()),
# Deny all other traffic
"deny_out": lambda ctx: [ctx.all_traffic],
# Register per-host rules
"rules": {
"api.example.com": [
{
Expand All @@ -292,48 +276,13 @@
})
```

### Selector callbacks for `allowOut` and `denyOut`

`allowOut` and `denyOut` accept either a static list (as shown above) or a **selector callback** that receives a context object — `{ allTraffic, rules }` in JavaScript and `ctx.all_traffic` / `ctx.rules` in Python. This lets you derive policies from the registered rule hosts without duplicating them, and provides a typed alternative to importing `ALL_TRAFFIC`.

- `allTraffic` (JS) / `ctx.all_traffic` (Python) is the literal `'0.0.0.0/0'`.
- `rules` is a `Map` (Python `Mapping`) view of `network.rules`.

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox } from 'e2b'

// Block all egress except an explicit allowlist
await Sandbox.create({
network: {
denyOut: ({ allTraffic }) => [allTraffic], // allTraffic === '0.0.0.0/0'
allowOut: ['1.1.1.1', '8.8.8.0/24'],
},
})
```
```python Python
from e2b import Sandbox

Sandbox.create(
network={
"deny_out": lambda ctx: [ctx.all_traffic],
"allow_out": ["1.1.1.1", "8.8.8.0/24"],
},
)
```
</CodeGroup>

<Note>
The selector form (`({ allTraffic }) => [allTraffic]` / `lambda ctx: [ctx.all_traffic]`) is the recommended way to express "everything". The `ALL_TRAFFIC` constant is still exported for backward compatibility.
</Note>

### Updating network settings on a running sandbox

You can update the network configuration of an already running sandbox using `updateNetwork` (JavaScript) or `update_network` (Python). This replaces the current egress rules with the provided configuration without restarting the sandbox.

<CodeGroup>
```js JavaScript & TypeScript
import { Sandbox, ALL_TRAFFIC } from 'e2b'
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

Expand All @@ -344,15 +293,15 @@

// Replace with an allow-list only
await sandbox.updateNetwork({
denyOut: [ALL_TRAFFIC],
denyOut: ({ allTraffic }) => [allTraffic],
allowOut: ['api.example.com'],
})

// Toggle internet access without recreating the sandbox
await sandbox.updateNetwork({ allowInternetAccess: false })
```
```python Python
from e2b import Sandbox, ALL_TRAFFIC
from e2b import Sandbox

sandbox = Sandbox.create()

Expand All @@ -361,7 +310,7 @@

# Replace with an allow-list only
sandbox.update_network({
"deny_out": [ALL_TRAFFIC],
"deny_out": lambda ctx: [ctx.all_traffic],
"allow_out": ["api.example.com"],
})

Expand All @@ -371,10 +320,10 @@
</CodeGroup>

<Note>
`updateNetwork` / `update_network` **replaces** the current egress configuration — it does not merge with the existing rules. Calling it with an empty object (`updateNetwork({})` / `update_network({})`) clears all `allowOut` / `denyOut` / per-host rules set at create time.
`updateNetwork` / `update_network` **replaces** the current egress configuration — it does not merge with the existing rules. Calling it with an empty object (`updateNetwork({})` / `update_network({})`) clears all allow and deny rules set at create time.
</Note>

The create-only options `allowPublicTraffic` and `maskRequestHost` cannot be changed after the sandbox is created.
Create-only options such as `allowPublicTraffic` / `allow_public_traffic`, `maskRequestHost` / `mask_request_host` and network rules in `network.rules` cannot be changed after the sandbox is created.

## Sandbox public URL
Every sandbox has a public URL that can be used to access running services inside the sandbox.
Expand Down Expand Up @@ -415,7 +364,7 @@

## Restricting public access to sandbox URLs

By default, sandbox URLs are publicly accessible. You can restrict access to require authentication using the `allowPublicTraffic` option:
By default, sandbox URLs are publicly accessible. You can restrict access to require authentication using the `allowPublicTraffic` / `allow_public_traffic` option:

<CodeGroup>
```js JavaScript & TypeScript
Expand Down Expand Up @@ -481,7 +430,7 @@
```
</CodeGroup>

When `allowPublicTraffic` is set to `false`, all requests to the sandbox's public URLs must include the `e2b-traffic-access-token` header with the value from `sandbox.trafficAccessToken`.
When `allowPublicTraffic` / `allow_public_traffic` is set to a falsy value, all requests to the sandbox's public URLs must include the `e2b-traffic-access-token` header with the value from `sandbox.trafficAccessToken` / `sandbox.traffic_access_token`.

Check warning on line 433 in docs/sandbox/internet-access.mdx

View check run for this annotation

Mintlify / Mintlify Validation (e2b) - vale-spellcheck

docs/sandbox/internet-access.mdx#L433

Did you really mean 'falsy'?

## Connecting to a server running inside the sandbox
You can start a server inside the sandbox and connect to it using the approach above.
Expand Down Expand Up @@ -577,7 +526,7 @@

## Masking request host headers

You can customize the `Host` header that gets sent to services running inside the sandbox using the `maskRequestHost` option. This is useful when your application expects a specific host format.
You can customize the `Host` header that gets sent to services running inside the sandbox using the `maskRequestHost` / `mask_request_host` option. This is useful when your application expects a specific host format.

<CodeGroup>
```js JavaScript & TypeScript
Expand Down