Configure the network egress jail

The jail is on by default. It blocks private, link-local and connected networks while allowing internet access, DNS and explicitly allowed IPs. Agents get a private IPv4-only network namespace; ordinary container shells do not.

With the PyPI launcher, edit ~/.config/claude-sandbox.conf on the host. Follow container configuration to mount it. In your own devcontainer, edit /etc/claude-sandbox.conf from a terminal outside the agent, and reapply changes after rebuilding or reinstalling.

Add the one required container device

The PyPI launcher supplies /dev/net/tun automatically. For your own devcontainer, add this run argument and rebuild:

"runArgs": ["--device=/dev/net/tun"]

Missing tun, pasta or namespace support makes agent launch fail closed. Use rootless Podman: rootful Docker cannot host the default jail.

Keep a lab device or internal forge reachable

Add one bare IP per line:

allow-ip = 172.23.1.3

This grants access to that device, not just one service. Review each addition.

Note

DLS: Diamond GitLab The shipped config includes allow-ip = 172.23.142.119 for Diamond GitLab. Retain that line if you replace the config and need forge access. Authentication alone does not make a blocked internal IP reachable.

Reach services on the host’s loopback

Use a relay port for services on 127.0.0.1; allow-ip does not route loopback into the jail:

local-port = 5432

The shipped local-model-port = 1920 relays lllm2’s API for every agent and enables Pi’s model discovery. Other ports use repeatable local-port lines. Every relayed port exposes the whole service behind it.

The outer container must share the service’s network namespace. The PyPI launcher uses host networking by default; --bridge prevents its loopback from reaching host-local services. A custom devcontainer needs host networking when the service runs on the host.

Let a browser login reach the agent

A callback relay lets a host browser reach a login server inside the agent’s private loopback. Enable only the fixed ports you need:

callback-port = 53692   # Pi's Claude subscription login
callback-port = 1455    # Codex browser login

The shipped examples are commented out. Ports cannot overlap local-port or local-model-port. If a host port is already occupied, the session warns and skips that relay; use the provider’s paste-code, callback-URL or device-login alternative where available.

The browser must reach the outer container’s loopback. For a remote machine, forward the port through your editor or SSH. Claude Code’s variable callback port uses its code-paste flow instead of a fixed relay.

A note on Channel Access for Claude

Warning

DLS: Channel Access needs unicast LAN broadcast discovery does not cross the agent’s private network namespace. Set EPICS_CA_ADDR_LIST to the device IPs, forward it with pass-env, and allow each IP with allow-ip. Ordinary shells in a host-network container retain broadcast access.

See Configuration for all keys and overrides, and the threat model for what the jail does and does not protect.