Skip to content

Network filtering

A sandbox profile's network axis controls where an agent's traffic may go. tclaude’s built-in sandbox enforces it with one of two engines: a packet engine (the Linux default — a private network namespace with a default-drop firewall and a DNS broker) and a proxy engine (network.engine: "proxy" — an empty namespace whose only way out is a filtering proxy that decides on the name the client asked for). One launch uses exactly one engine; combining them is refused.

This page covers how profiles express network policy, how each engine enforces it, and where each engine's guarantees end. The profile model itself is on the sandboxing page.

Expressing policy in a profile

A profile's network block authors a baseline — inherit, allow, or deny (the legacy network_access: internet|none spelling is still accepted) — plus allow and deny rows. Composed across scopes, the rules resolve each launch to an effective open, closed, or list-filtered posture. Rows are built from these selectors:

  • host — an exact DNS name.
  • domain — a DNS domain, optionally with include_subdomains; matching is label-bound, so example.com never matches notexample.com.
  • cidr — IP-literal packet authority. A CIDR row carries no DNS authority: it does not admit DNS names whose answers happen to fall inside it.
  • loopback — the host's own loopback services.
  • ports[] — TCP and UDP both (QUIC counts as UDP); empty means all ports.

The sandbox-profile network editor: baseline, engine, and namespace selectors above authored deny rows

The sandbox-profile network editor: baseline, engine, and namespace selectors above authored deny rows

Deny rows compose as a union and win every overlap; rule order is irrelevant. Under a deny baseline, allow rows are unlocks; under an allow baseline, deny rows are restrictions — the editor labels the redundant cases instead of rejecting them.

Packs

Rather than hand-maintaining vendor endpoints, profiles reference release-owned packs, stored as stable IDs, expanded at resolution time, and frozen into launch snapshots. The current registry:

Pack Covers
net-local Unscoped loopback — local model servers (Ollama, LM Studio, llama.cpp), Codex OSS mode, host-local dev services
net-anthropic Claude Code with an API key or a Claude subscription sign-in (api.anthropic.com:443, plus platform.claude.com:443, where a subscription login refreshes its token)
net-openai-codex Direct OpenAI API-key endpoints (api.openai.com:443)
net-openai-chatgpt ChatGPT-signed-in Codex (chatgpt.com:443, auth.openai.com:443)
net-github-copilot GitHub Copilot CLI model and auth traffic
net-google-gemini-api Gemini CLI signed in with an API key (generativelanguage.googleapis.com:443)
net-google-gemini-login Gemini CLI signed in with Google (cloudcode-pa.googleapis.com:443, oauth2.googleapis.com:443)
net-github GitHub (github.com, api.github.com, and friends)
net-go-modules The Go module proxy and checksum database
net-npm The npm registry

deny_packs is the mirror image. New Deny-all drafts pre-select net-local, net-anthropic, net-openai-codex, and net-openai-chatgpt; the packs stay ordinary editable choices afterward. The saved shape keeps intent rather than copying endpoints:

{
  "network": {
    "baseline": "deny",
    "packs": ["net-local", "net-anthropic", "net-github"],
    "deny_packs": ["net-npm"],
    "allow": [{"domain": "example.internal", "ports": [443]}],
    "deny": [{"host": "telemetry.example.internal"}]
  }
}

Namespace, and the unix-socket axis

network.namespace is independent of the baseline: host shares the host network; private gives the launch its own Linux network namespace routed through pasta with default-accept — it separates abstract Unix sockets and host loopback from the agent without making IP traffic deny-by-default. It is supported with tclaude’s sandbox alone on Linux for Claude Code, Codex, OpenCode, Copilot, Gemini CLI, pi and shell launches, and refuses elsewhere rather than falling back. A private namespace in a global or included profile cannot be widened by a child.

The unix_sockets axis (mode: open|closed|list plus path/path_glob entries; ** refused; the agentd socket is a non-removable floor) governs filesystem Unix sockets. Authoring it as closed or a list on an otherwise host-open profile gets a host-network constructed root on Linux: a fresh filesystem root and PID namespace with the listed sockets bound back, but no network namespace — host IP networking and the IDE bridge keep working. That posture is permanently rated partially enforced: with the host network namespace shared, abstract-namespace sockets (@…) are not filesystem objects and no mount plan can hide them. Close network access too if those must be confined.

Composition across scopes

Allow authority intersects across the global, group, and explicit tiers while deny authority unions — (B1−D1)∩(B2−D2) = (B1∩B2)−(D1∪D2) — and closed dominates. Unix-socket lists intersect. network.engine is the one precedence field: most explicit wins (explicit > group > global), with a disclosure when composition was overridden.

Because allow lists intersect, a destination is reachable only if every tier that authors an allow list allows it. A group profile cannot add a host that the global profile's list leaves out. When two or more tiers author lists and the intersection drops entries, the resolved profile carries a composition warning that names, per tier, what was dropped or narrowed. The spawn dialog, the profile editor and tclaude agent sandbox-profiles plan show it. If the dropped entry is the harness's model endpoint, the model-transport refusal below names the tier that allowed it and the tier that did not. Fix it in the tier that lacks it, or give the global tier no list (baseline: "allow" or no network policy) so the group list alone decides.

The three postures

  • Open baseline (or omitted / legacy internet) → host-open: the host network namespace, host loopback services and ambient Unix sockets included. Ambient privileged sockets such as docker.sock are a named residual under an inherited root.
  • Closed (none) → isolated-with-agentd: a fresh network namespace with only loopback up, a fresh PID namespace, and a constructed root with the agentd socket bound read-only. This severs IDE bridges and host-local model servers, so hosted-only harnesses are refused outright; Codex proceeds only with the explicit TCLAUDE_OFFLINE_MODEL=1 operator assertion. On macOS, Seatbelt denies outbound and bind (agentd socket excepted) but provides no PID isolation, no constructed root, and — deliberately — no loopback exception. The dashboard spawn dialog's "Allow launch with unenforced rules" checkbox can widen this closed-network gap for one fresh launch, never saved or inherited, recorded as operator_unenforced_launch_override.
  • List → filtered, through whichever engine the profile deploys.

The packet engine

The Linux default for a list or deny policy under tclaude’s sandbox. Four building blocks, assembled per launch:

  1. bubblewrap creates user, network, PID, and mount namespaces with no connectivity, presenting the harness as the invoking numeric UID/GID. Files created in authorized host binds therefore remain owned by that host identity.
  2. The outside supervisor joins the user namespace that owns the network namespace, then installs a default-drop nftables output policy (inet tclaude_filter) as one atomic transaction with timed per-rule IPv4/IPv6 sets. The sandbox bootstrap holds no capabilities, drops and verifies all capability sets, sets no-new-privileges, and gates the harness until setup completes.
  3. Rootless pasta provides outbound-only connectivity — no inbound forwards, no splice shortcuts. Harness exec is gated until the policy and pasta are both verified; if pasta or the broker dies, the supervisor kills the sandbox. In caller-identity mode the supervisor starts pasta from the network namespace's owning user namespace before it joins the nested network namespace; this keeps pasta and nft authority independent of the harness identity.
  4. A tclaude DNS broker at 127.0.0.53 (a real listener on port 1053 behind an nft redirect) answers only authored names. Each admitted A/AAAA answer is leased into the matching nft set for the observed DNS TTL, capped at one hour. Sealed memfds pin the nft batch and the sandbox's /etc/hosts/resolv.conf, so a hosts-file mapping cannot bypass the selectors. SVCB/HTTPS records are stripped, which blocks ECH config delivery and keeps TLS SNI observable — defense-in-depth.

DNS names are enforced at the DNS-to-IP boundary: an allowed name admits the addresses its lookup returned, so another site hosted on a shared IP is also reachable until the lease expires, and an established connection survives expiry. New flows always need a current lease — an agent that performs no fresh lookup after expiry cannot open another connection. Host, domain, CIDR, and loopback selectors rate Full with that boundary stated; DNS-name deny rows are Full under a deny baseline and Partial under an allow baseline (another address for the same service, or encrypted DNS that bypasses the broker, can remain reachable).

Host-loopback rows map to the synthetic name host.tclaude.internal (169.254.2.2 / fd00::2), filtered by the authored ports; 127.0.0.1 and ::1 stay private to the sandbox. Known gap: the synthetic addresses are not reserved from CIDR or DNS-derived rules, so either kind of rule can also reach host loopback on its authored ports — a DNS-rebinding route to host services.

The packet engine is enforced with tclaude’s sandbox alone for Claude Code, Codex, OpenCode, Gemini CLI, pi and shell launches on Linux. When OpenCode supplies a strict explicit- provider configuration, tclaude checks that provider endpoint against the authored rules. An OpenCode route tclaude cannot inspect is left to those rules: the launch proceeds, and the packet floor allows or blocks the actual request. The launch then carries a notice saying the model endpoint was not checked, and why resolution stopped; see OpenCode under a filtered network. If a prerequisite is missing before enforcement is selected — bwrap, pasta, nft, or nsenter resolved through trust-walked paths (no group/world-writable path component, a regular executable target; ownership is not checked, so a user-installed one is accepted), pidfd support, the pasta feature probe — the filtered rules widen to host-open with a persisted warning; after enforcement is selected, failures are fail-closed.

The model-transport gate

A filtered launch refuses (unsupported_filtered_model_transport) unless the authored list covers the harness's resolved model endpoint — tclaude never fabricates provider resolution or quietly punches a hole:

  • Claude Code resolves its route from the launch environment, and inspects the cached remote managed settings for provider routing. Claude Code can re-route live on its hourly settings poll; a route moved that way is denied fail-closed at the packet floor for new flows. A Claude subscription login also refreshes its access token at platform.claude.com:443. That is not model traffic, so it does not gate the launch: when a subscription-signed-in launch's rules cannot reach it, the launch carries a warning instead, since the model keeps working until the current token (about 8 hours) expires. net-anthropic covers both hosts.
  • Codex is read through the app-server config/read request — including the MDM and enterprise cloud-config layers no local file exposes. ChatGPT sign-in resolves to chatgpt_base_url plus the constant auth.openai.com refresh endpoint (the net-openai-chatgpt pack covers both). Credential routes tclaude cannot inspect refuse.
  • A foreign HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY in the pre-injection launch environment refuses filtered launch: the real destination would sit behind a proxy this seam cannot resolve.

The proxy engine

network.engine: "proxy" replaces the packet machinery with a different bargain. On Linux the launch gets an empty network namespace — nothing inside has a route anywhere — and the only way out is a host-side filtering proxy reached through a single loopback listener whose descriptor is bound into the namespace by a capability-free bootstrap and passed out; the host never binds into the sandbox.

The proxy speaks HTTP CONNECT / absolute-form HTTP and SOCKS5 (CONNECT only — no auth, no UDP ASSOCIATE), both carriages feeding one evaluator. It decides on the name the client requests, before resolution: no DNS lease, no shared-IP authority, no TTL window. There is no CA and no TLS interception. The trade-off is that only proxy-cooperating clients work — proxy-unaware programs, UDP, QUIC, ICMP, and raw sockets are blocked (fail closed), not filtered.

The launcher owns all eight proxy environment variables (HTTP_PROXY/HTTPS_PROXY and lowercase forms pointing at the listener, ALL_PROXY=socks5h://…, and NO_PROXY forced empty with a disclosure when the host carried a value), injected after the model-transport gate reads the pre-injection environment — so tclaude's own variables never trigger the foreign-proxy refusal. A loopback-only /etc/hosts and refusal of resolver sockets on the unix-socket or filesystem axis preserve name authority.

Policy details differ from the packet engine where the mechanism differs: allow cidr rows are literal-only (Partial — a cooperating client that sends a name is judged on the name); deny rows are re-checked against resolved addresses; and in allowlist modes a private-destination blocker refuses loopback, link-local, RFC1918, CGNAT, ULA, and unspecified addresses unless authored. CIDR rows overlapping loopback-row authority are refused at authoring time.

Prerequisites on Linux are just bubblewrap namespaces and pidfds — the proxy engine works on hosts where the packet gateway cannot. A host that cannot build the floor refuses rather than widening; the only widening left is an unactivated harness/platform cell, which leaves rules unenforced with a notice.

macOS

The proxy engine is what brings egress filtering to macOS, rated Partial. The Darwin launcher binds a host-loopback ephemeral port, renders a Seatbelt floor that denies all listeners and all outbound except that port and the agentd socket, and injects the same proxy environment. Darwin's NetworkList cell is capped at Partial permanently: Seatbelt's localhost token means every address of this machine, so the floor's scope is a port set, not an address set — a second service on an allowed port bound to a non-loopback local address is reachable.

Activation

Enforcement is claimed only where a real harness/platform smoke has proven it. The current activation record: Linux — Claude Code, Codex, OpenCode, Gemini CLI, pi; macOS — Claude Code, Codex, OpenCode (pinned against Claude Code 2.1.220, Codex 0.145.0, OpenCode 1.18.6, Gemini CLI 0.62.0, pi 1.5.0). Selecting the proxy engine for a non-activated cell leaves the rules unenforced with a notice. Engine defaults do not flip: unset means the packet engine on Linux and historical behavior on macOS.

OpenCode's local-provider presets compose under either engine. When tclaude cannot inspect their model route, launch proceeds without model-endpoint coverage validation and the authored rules remain the entire egress authority.

Group routes ride the proxy

Named group routes are carried by this engine: a sandboxed agent dials a synthetic *.route.tclaude.invalid hostname, and the proxy verifies group membership and the route lease before dialing the route adapter's loopback endpoint. Routes are how a sandboxed agent reaches a peer's published service across the wall; they work for proxy-cooperating clients only.

Copilot

tclaude’s sandbox fully supports Copilot CLI on Linux and macOS for filesystem confinement, and it has its own net-github-copilot pack — but it sits outside both filtering engines today. It is not packet-filtered (destination rules widen to host-open with a disclosure) and not proxy-activated (destination rules under the proxy engine leave rules unenforced with a notice, and combining Copilot destination rules with a private namespace and the proxy engine is an explicit refusal). Its one private-namespace option is default-accept routing via network.namespace: private. Author network lists for Copilot with that in mind: they document intent, they do not yet enforce it.

Gemini CLI

Gemini CLI launches are enforced by the Linux packet gateway, the same as Claude Code, Codex, OpenCode, pi and shell. On Linux the proxy engine works for Gemini too; it is not yet activated on macOS. Gemini is a Node program, and on current Node its model client honours the proxy variables only when NODE_USE_ENV_PROXY=1 is set, so every Gemini launch under tclaude's sandbox exports it. The agent's own Node commands inherit it, which has one visible effect behind the proxy engine: a Node program that calls a server it started on localhost sends that request to the proxy, which treats loopback as the host's, so it is refused, or with a loopback row, reaches the host's service on that port instead of the sandbox's. Gemini's telemetry origin (play.googleapis.com) is not in either Gemini pack, so the proxy refuses it and Gemini carries on without it. tclaude resolves the model route from Gemini's own selected auth type (settings.json security.auth.selectedType) and checks it against the authored list:

  • gemini-api-key needs net-google-gemini-api.
  • oauth-personal (Google sign-in) needs net-google-gemini-login.

The launch is refused, with a reason, in these cases: - No auth type is selected (the pane would stop on Gemini's sign-in dialog). - The auth type is another one (Vertex AI, compute ADC, a gateway). - CODE_ASSIST_ENDPOINT, GOOGLE_GEMINI_BASE_URL, GOOGLE_VERTEX_BASE_URL or GOOGLE_CLOUD_UNIVERSE_DOMAIN is set. - The .env file Gemini loads sets one of those variables, or a proxy.

Unlike the other harnesses' routes, these were read from the Gemini CLI source rather than observed on an authenticated run. A wrong guess fails closed: the wall denies the traffic. The first browser sign-in, telemetry, web tools and MCP servers need their own destinations.

pi

pi launches are enforced by the Linux packet gateway, and on Linux the proxy engine works for pi too; it is not activated on macOS. Under either engine pi runs offline and needs the same model route. tclaude resolves the model route from the model's provider (--model provider/id, else defaultProvider in pi's settings.json, and on resume the model the session records) and checks it against the authored list: anthropic needs net-anthropic, openai needs net-openai-codex, openai-codex (ChatGPT sign-in) needs net-openai-chatgpt, and google needs net-google-gemini-api. The other reviewed providers (openrouter, xai, groq, mistral, deepseek, cerebras, together, fireworks, zai, moonshotai, huggingface) need an allow row for their API host, and a provider with a baseUrl in pi's models.json needs that endpoint.

The launch is refused, with a reason, when the provider is none of these (an extension's provider, Bedrock, Vertex, Azure, GitHub Copilot), when no provider can be read, when the project's .pi/settings.json picks a different default provider, or when pi's settings set httpProxy.

A filtered pi launch runs offline: tclaude exports PI_OFFLINE=1, PI_SKIP_VERSION_CHECK=1 and PI_TELEMETRY=0, so pi makes no version check, catalog refresh, install-telemetry call or fd/rg download, and the model route is the only destination it needs. Like the other harnesses' routes, these were read from pi's source at 1.1.0. Web tools, MCP servers and a first /login need their own destinations.

Troubleshooting

Symptom Likely cause
A connection that worked stops; retry after a new lookup succeeds Packet engine DNS lease expired — new flows need a fresh lookup; established flows were never cut
An allowed name intermittently reaches an unrelated site Shared-IP reuse inside the lease window — the DNS-to-IP boundary, not a rule bug
Blocked host: connect hangs or EHOSTUNREACH/timeout Packet engine default-drop — denied packets are dropped, not rejected
Blocked host under the proxy engine: immediate proxy error Expected — the proxy refuses the CONNECT by name
curl works but another tool cannot reach anything (proxy engine) The tool ignores proxy environment variables; proxy-unaware clients are blocked, not filtered
UDP/QUIC traffic silently fails under the proxy engine By design — only TCP through CONNECT is carried
Launch refused: unsupported_filtered_model_transport The authored list does not cover the resolved provider endpoint — add the matching pack or use network open
Claude Code loses the model hours into a filtered session A subscription login cannot reach platform.claude.com:443 to refresh its token; the launch warned about it. Include net-anthropic or allow that host
Launch refused over HTTP_PROXY/ALL_PROXY A foreign proxy variable in the launch environment; remove it or use network open
Filtered rules silently became host-open (warning recorded) A packet-engine prerequisite (bwrap, pasta, nft, pidfds) was missing before enforcement was selected
Rules recorded but "not enforced" notice on the launch Non-activated engine cell — e.g. Copilot, or macOS packet filtering
Host loopback reachable despite no loopback row The synthetic-address reservation gap — a CIDR or DNS-derived rule can reach host loopback on its ports

See also

  • Sandboxing — the profile model, implementations, and composition rules.
  • Group routes — publishing services across the wall.
  • Credential proxies — git/GitHub/Linear access that needs no network hole at all.