Bring your own proxy (BYOP)

Route outbound sandbox traffic through a SOCKS5 proxy you run

Bring your own proxy is currently in private beta. If you’d like access, please reach out to us at [e-mail].

With Bring your own proxy (BYOP), you can route outbound TCP connections from your sandbox through a SOCKS5 proxy you operate.

Unlike proxy tunneling, nothing runs inside the sandbox. There is no custom template, no proxy client, and no in-guest configuration, so the code running in the sandbox cannot see the proxy or route around it.

Typical reasons to use it:

• Give all sandbox traffic a stable, allowlistable source IP. E2B does not offer static egress IPs on any plan, see Egress IP ranges.
• Reach a corporate network, a VPN, or internal services that only accept traffic from your own network.
• Log or inspect sandbox egress in your own infrastructure.

How it works

• Tunneling happens on the host, after filtering. Your allow and deny lists are evaluated first, so a connection that denyOut blocks never reaches your proxy. See Internet access for the filtering rules.
• TCP only. UDP based traffic, including DNS and QUIC or HTTP/3, is not tunneled. It leaves the sandbox the usual way and stays subject to your allow and deny lists.
• Hostname destinations use remote DNS. When a connection is allowed by a domain entry in allowOut and the destination is a hostname, E2B hands that hostname to your proxy (SOCKS5 ATYP=domain) so your proxy does the final resolution. An IP-literal destination, including a numeric HTTP Host value matched by '*', is sent as a SOCKS5 IP address.
• Per-host request transforms still apply. Header injection and workload identity token resolution happen before the connection is dialed through your proxy.
• The proxy hostname is re-resolved at dial time and the resolved address is pinned for that connection, so a DNS change cannot redirect a connection that is already being established.
• Egress fails closed. If the proxy is unreachable, or the address does not speak SOCKS5, outbound connections from the sandbox fail instead of falling back to a direct connection. Make sure the proxy is reachable from the public internet before you point sandboxes at it.

Configuring a proxy

Pass network.egressProxy / network["egress_proxy"] when you create the sandbox:

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create({
  network: {
    egressProxy: {
      address: 'proxy.example.com:1080',
      username: 'proxy-user',
      password: 'proxy-password',
    },
  },
})

You can combine it with the rest of the network configuration. Here all traffic is denied except api.example.com, and the traffic that is allowed goes through your proxy:

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create({
  network: {
    allowOut: ['api.example.com'],
    denyOut: ({ allTraffic }) => [allTraffic],
    egressProxy: { address: 'proxy.example.com:1080' },
  },
})

Using a wildcard with BYOP

Add the wildcard and deny-all entry to your proxy configuration:

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create({
  network: {
    allowOut: ['*'],
    denyOut: ['0.0.0.0/0'],
    egressProxy: { address: 'proxy.example.com:1080' },
  },
})

Inside this sandbox, use ordinary requests without client-side proxy flags:

# Through BYOP: the destination sees your proxy's egress IP
curl --max-time 10 https://api.ipify.org

# Through BYOP: destination IP 1.1.1.1, port 80
# Your proxy policy can reject this IP-literal destination
curl --max-time 10 http://1.1.1.1

# Blocked before BYOP: no TLS SNI and no IP allowance
curl --max-time 10 https://1.1.1.1

UDP DNS to 8.8.8.8:53 leaves directly, outside BYOP, because of the automatic nameserver allowance. Your proxy’s policy does not apply to it. See Catch-all wildcard for filtering details.

Fields

Field	Required	Description
address	yes	SOCKS5 proxy address in host:port form, for example proxy.example.com:1080. The host can be a hostname or an IP literal, and the port must be between 1 and 65535.
username	no	SOCKS5 username (RFC 1929), up to 255 bytes.
password	no	SOCKS5 password, up to 255 bytes. Only valid together with username.

The proxy has to be reachable from E2B’s infrastructure. A hostname that does not resolve, or that resolves to a private or otherwise internal address range, is rejected at creation time, before the sandbox exists.

Updating a running sandbox

updateNetwork / update_network sets or replaces the proxy on a sandbox that is already running, with no restart:

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

// Start tunneling on the running sandbox
await sandbox.updateNetwork({
  allowOut: ['api.example.com'],
  denyOut: ({ allTraffic }) => [allTraffic],
  egressProxy: { address: 'proxy.example.com:1080' },
})

// Stop tunneling: an update without egressProxy clears it
await sandbox.updateNetwork({})

The update replaces the whole configuration instead of merging into it, so omitting the proxy clears it. A network update that leaves the field out stops tunneling and sends the sandbox’s traffic out directly, even when the update was only meant to change the allow and deny lists. Repeat the proxy configuration in every update where you want to keep it.

An update that fails validation changes nothing, so the sandbox keeps tunneling through the proxy it already had.

Reading the current configuration

The sandbox info reports the active proxy under network:

JavaScript & TypeScript

const info = await sandbox.getInfo()

console.log(info.network?.egressProxy)
// { address: 'proxy.example.com:1080', username: 'proxy-user' }

The password is never returned.

Errors

An invalid proxy configuration is rejected when the sandbox is created, so a rejected create leaves nothing behind.

Error	Cause
Egress proxy (network.egressProxy) is not enabled for this team.	Your team is not in the private beta yet.
Invalid egress proxy config: egress proxy address must be in host:port form	address is missing the port or is not in host:port form.
Invalid egress proxy config: egress proxy port ... is not a valid 1-65535 value	The port is out of range or not a number.
Invalid egress proxy config: resolve egress proxy host ...	The proxy hostname does not resolve.
Invalid egress proxy config: egress proxy endpoint resolves to an internal / denied IP range	The proxy address points into a private or internal range.
Invalid egress proxy config: egress proxy password must be empty when username is empty	A password was set without a username.
validation error: ... maximum string length is 255	The username or password is over the 255 byte SOCKS5 limit. This one is a schema error rather than a proxy config error, because the request is rejected before the proxy configuration is read.

Self-hosted deployments

BYOP is available on E2B Cloud and in BYOC environments. Deployments built from the open source e2b-dev/infra repository cannot tunnel sandbox egress through a SOCKS5 proxy, and a sandbox that names one is rejected as unsupported by the orchestrator build.