Skip to content

Network & egress

Most sandboxes do not need an internet connection just to run commands. On a fresh install, bhatti create --name dev gives the guest no NIC. The CLI, files, shell and host-to-guest proxy still work over vsock. Enable only the connections your agent actually needs.

NeedCreate flagsResult
No outbound networkingNone (or --egress none)No guest NIC or network gateway.
A few public API hosts--allow-host HOST (repeatable)NIC with default-deny egress and those host rules.
A private destination--allow-cidr CIDRNIC with default-deny egress and an explicit CIDR rule; hard-denied destinations stay blocked.
Public internet--net (equivalent to --egress public)Public egress, but not private networks or siblings.
Same-owner sandbox traffic--allow-siblingsNIC with sibling TCP/UDP permitted for the sending sandbox, not public egress.

With no flags the server’s default_egress applies (none on fresh installs). --egress deny explicitly creates a NIC while denying outbound traffic except allow rules. --allow-host, --allow-cidr or --allow-siblings without an explicit posture imply deny. You can configure default_egress: public server-wide, but per-sandbox flags are easier to review. A fork with create --from inherits the source’s policy and cannot override these flags; create a fresh sandbox for a different policy.

Offline worker. Run a command or use an existing local tier without granting a NIC:

Terminal window
bhatti create --name offline --label role=offline
bhatti exec offline -- sh -c 'echo ready'

Model API and GitHub only. DNS-aware exact host rules permit named public services without opening the rest of the internet. Add every actual host the client calls (GitHub may require additional endpoints for its particular workflow).

Terminal window
bhatti create --name code-agent \
--allow-host api.openai.com \
--allow-host api.github.com
bhatti inspect code-agent

An allow-host rule does not override a name that resolves to a private address. Use --allow-cidr for an explicitly approved private destination. Host addresses are denied except for the exact address/port pairs of configured daemon TCP service listeners when the remaining egress policy permits them: public listeners can be reachable under public egress, while private listener addresses need an explicit CIDR allowance. Other host ports, the netd gateway, another owner’s network, loopback and cloud metadata remain blocked. API authentication still applies.

Full public internet. For an agent that really needs package registries, arbitrary documentation sites and APIs:

Terminal window
bhatti create --name browser --image browser --net

Same-owner siblings still need their own opt-in, and private daemon-service addresses still need an explicit CIDR allowance. A public URL served by your sandbox is a different direction of traffic.

Sandboxes talking to each other. Each receiver needs a NIC; each sender needs the sibling opt-in. Create both with it if they will initiate connections in both directions:

Terminal window
bhatti create --name coordinator --allow-siblings
bhatti create --name worker --allow-siblings
bhatti inspect worker
# With jq on the CLI machine, read the worker's numeric network IP:
WORKER_IP=$(bhatti inspect worker --json | jq -r '.ip')
bhatti exec coordinator -- curl "http://$WORKER_IP:3000/"

The example assumes the worker is listening on port 3000. Use its numeric Network → IP address: v2.5.10 does not resolve sandbox names or <sandbox>.sb names. The gateway forwards only policy-permitted DNS queries to an external resolver; --allow-siblings does not authorize DNS names or grant open internet access. Other owners’ sandboxes remain isolated even with CIDR allow rules.

Run bhatti inspect NAME and read Network → IP, Egress, Siblings, Allow hosts, Allow CIDRs. IP is empty without a NIC; a 100.64.* address means the guest is on its owner’s userspace gateway, not directly reachable from the host LAN. bhatti ls -o wide shows addresses and labels across sandboxes. Test from the guest when debugging a rule:

Terminal window
bhatti exec code-agent -- curl -I https://api.github.com
bhatti exec code-agent -- curl -I https://example.org

A denied route or DNS response is an egress policy result, not evidence that the API daemon needs a public listener. See network internals for the rule ordering, DNS checks, hard-denied targets and link authentication. Network policy is set at creation; bhatti edit changes names, labels and thermal settings, not egress rules.

bhatti publish exposes a guest service to incoming HTTP/WebSocket requests using the host’s vsock proxy; it does not grant the guest a NIC. Public HTTPS alias URLs require custom-domain/TLS setup. Without domain mode, the separate public_proxy_listen setting can serve unauthenticated path-based HTTP URLs for development/testing. With neither public proxy configured, the control API’s /sandboxes/:id/proxy/:port/ fallback still requires a bearer token. For private TCP access, bhatti forward binds loopback on the CLI machine by default and tunnels to the guest port. None of these ingress paths gives an agent inside the guest internet access.

For API credentials, pair scoped host rules with Credentials for agents instead of injecting the real key into an untrusted guest environment.