Network

Control a sandbox's outbound access with the E2B SDK's allowInternetAccess and network create options, and change it later with sandbox.updateNetwork(). The gateway turns these settings into a Kibotos network policyThe rules that decide where a Workspace's outbound traffic may go: its mode, destination rules, and any Egress or Resolver it references. A new Workspace has no network access by default., and can send the sandbox's outbound TCP through your own SOCKS5 proxy.

Supported endpoints and optionsCopy Anchor Link

For inbound access to application ports, see Application ports.

Outbound policyCopy Anchor Link

The following create options deny all outbound traffic except to one range:

const sandbox = await Sandbox.create('kibotos-minimal', {
  ...connectionOptions,
  allowInternetAccess: false,
  network: { allowOut: ['140.82.112.0/20'] },
});

connectionOptions stands for apiKey, domain, and the other connection options in the example on E2B compatibility.

How requests map to the policyCopy Anchor Link

The gateway translates each request into a policy mode and destination rules:

Denies all IPv4 means allow_internet_access: false, or denyOut containing 0.0.0.0/0 (ALL_TRAFFIC in the SDK). E2B sandboxes have IPv4-only outbound access, so on E2B this denies all outbound traffic. On Kibotos, the gateway therefore denies IPv6 as well.

For evaluation order and address family rules, see Network policy in the native API.

EntriesCopy Anchor Link

Entries are written as in E2B:

• Each item is one address or CIDR. denyOut does not accept domain names.
• Of the unspecified addresses, only 0.0.0.0/0 is accepted; ::/0 returns 400.
• A CIDR with host bits set takes effect as its network address, while getInfo() still echoes it as written.
• The two lists together hold at most 256 items, including the ::/0 the gateway adds. More returns 400.
• Private and special-purpose addresses cannot be opened, even in allowOut. Rejected connections fail immediately instead of waiting for a timeout.

Domain names and domain patterns in allowOut return 501 with the capability name network egress allowlist domains. As in E2B, a domain name without ALL_TRAFFIC returns 400 first. rules returns 501. Both are listed in Not supported.

DNSCopy Anchor Link

With allowOut or denyOut, DNS queries from the sandbox still work. The guest sends queries only to the node's link DNS address, and the node forwards them to the deployment's DNS servers. Neither list affects this.

On E2B, DNS is also denied in this case, unless allowOut includes the resolver.

Changing the networkCopy Anchor Link

As in E2B, a change replaces the whole outbound configuration, and fields you leave out are cleared.

• An empty change request clears all entries and opens public internet access.
• The gateway returns 204 after confirming that the new policy is in effect on the node, waiting at most 30 seconds.
• On timeout, the gateway returns 500 and states that the change may have been accepted.
• Concurrent changes return 409.
• Changing the network does not extend the sandbox's lifetime and does not change its tokens.

Egress proxyCopy Anchor Link

egressProxy makes the sandbox's outbound TCP leave through your own SOCKS5 proxy. The gateway saves the proxy as an EgressAn outbound SOCKS5 proxy that the caller runs. When a Workspace's network policy references it, TCP connections to the given ranges leave from the caller's network. and references it in the network policy for the destination ranges 0.0.0.0/0 and ::/0. For what an Egress is and how to manage it, see Egress.

The following create options send outbound TCP through a proxy with password authentication:

const sandbox = await Sandbox.create('kibotos-minimal', {
  ...connectionOptions,
  network: {
    egressProxy: {
      address: 'proxy.example.com:1080',
      username: 'sandbox',
      password: process.env.PROXY_PASSWORD,
    },
  },
});

To change the proxy later, call sandbox.updateNetwork({ egressProxy }) with the full proxy settings.

Proxy fieldsCopy Anchor Link

• In SDK 2.46.1, egressProxy has only these three fields and no TLS settings. The gateway connects to the proxy without TLS.
• Any other key in egressProxy returns 400.

Traffic through the proxyCopy Anchor Link

• What is forwarded: denyOut is evaluated first, and denied connections never reach the proxy. All other new TCP connections go through the proxy, with no blocking of private addresses, so addresses in the proxy's own network are reachable too.
• Traffic that bypasses the proxy: DNS queries still go to the node's link DNS address, and the node forwards them to the deployment's DNS servers without the proxy. Other UDP is not allowed under PUBLIC_INTERNET in the first place, so it does not go through the proxy either. Pings to proxied destinations are denied.
• When the proxy is unavailable: connections fail outright and do not fall back to going direct.
• Denying all outbound traffic while setting a proxy: the policy cannot be DENY_ALL, so the gateway uses PUBLIC_INTERNET with deny set to 0.0.0.0/0 and ::/0. All connections are still denied, and only DNS queries work.

Changing or removing the proxyCopy Anchor Link

• A change with egressProxy updates this sandbox's Egress in place, and must include the password every time. If the sandbox had no proxy, a new Egress is created.
• An in-place update does not change the policy's revision. The gateway returns 204 only after the Egress's new revision is in effect on the node.
• A change without egressProxy removes the proxy. The gateway first removes the reference, confirms that the change is in effect, and then deletes the Egress.
• If another client changes the policy to reference a different Egress, the gateway only removes the reference, and neither modifies nor deletes that Egress.

Egress cleanupCopy Anchor Link

• After a sandbox is deleted, the gateway deletes its Egress.
• Egresses of sandboxes deleted on expiration, and Egresses left behind when the gateway fails midway, are deleted by a cleanup that each gateway instance runs every 5 minutes.
• Egresses created less than 10 minutes ago are excluded from cleanup.

Fields returned by queriesCopy Anchor Link

GET /sandboxes/{id} and the list endpoint return the network configuration actually in effect. In the SDK, read these fields with getInfo(); see Sandboxes and lifecycle.

Passwords are write-only: network.egressProxy in getInfo() and the list endpoint never includes the password.

NotesCopy Anchor Link

• Destination rules need ctrl support. If ctrl does not advertise workspace.network_policy.destination_rules, requests with entries return 501 with the capability name network egress allow and deny lists, instead of falling back to the on/off switch only.
• The proxy needs Egress support in ctrl. If ctrl does not advertise workspace.network_policy.egress.socks5, requests with egressProxy return 501 with the capability name network egress proxy, instead of falling back to going direct.

Next stepsCopy Anchor Link

• Application ports: reach HTTP and WebSocket services in a sandbox.
• Network policy: how the native policy evaluates a destination.
• Egress: manage caller-owned proxies with kibo or the native API.