Network and egress

How DefenseClaw's egress proxy decides every site a sandboxed agent contacts, the open, balanced and strict network profiles, the blocklist, unblocks, asks, large-upload alerts and what the agent is told when it is blocked.

A sandbox has no network of its own. DefenseClaw watches its three ways out.

PathWhat happens
Web trafficGoes through DefenseClaw's egress proxy, which the sandbox reaches at host.openshell.internal through HTTPS_PROXY and HTTP_PROXY. The proxy decides and logs every site.
Model callsGo straight to the model provider through OpenShell, which adds the real credential outside the sandbox. This path bypasses the egress proxy. OpenShell opens the model hosts to the harness's own program only. For an npm or Python harness that is its node or python, so a script the agent runs with it reaches them too. The hooks still judge the tool call that starts the script.
Anything elseA client that ignores the proxy settings is refused by OpenShell, which files a connection request. DefenseClaw decides most of those itself and asks you about the rest (answer an ask).

The sandbox holds only a placeholder for the model credential. OpenShell forwards no request whose body carries a placeholder. Once a conversation shows one (the agent ran env, say), OpenShell refuses every later request of that conversation, model calls and hooks alike. The key is fine: start a new conversation with defenseclaw sandbox connect NAME, without --continue.

How a site is decided

The proxy checks each request in a fixed order and the first match decides. The table has every step; the diagram shows the layers. Every sandbox is decided by its own policy: another sandbox's pack, block list or unblocks never apply to it.

Safety checksthis machine, private networks, portsblocked; no unblock opens these
Your organization's listslisted, or off its allow-only list: blocked
Your block listblocked; remove the entry to open it
Your unblocks and allow listallowed
The blocklist feedblocked; you can unblock it
The network profileopen, balanced or strictdecides the rest (step 9)

List view for small screens. Use the expand button to open the drawing.

  1. 1.Safety checksthis machine, private networks, portsblocked; no unblock opens these
    • Your organization's lists
  2. 2.Your organization's listslisted, or off its allow-only list: blocked
    • Your block list
  3. 3.Your block listblocked; remove the entry to open it
    • Your unblocks and allow list
  4. 4.Your unblocks and allow listallowed
    • The blocklist feed
  5. 5.The blocklist feedblocked; you can unblock it
    • The network profile
  6. 6.The network profileopen, balanced or strictdecides the rest (step 9)
The egress proxy's checks, in order: the first that matches decides. When your organization turns unblocking off, unblocks do not count and the feed is checked before your allow list.
StepCheckResult
1This machine, link-local and cloud metadata addressesBlocked. Nothing opens them. Use --host-port PORT for one service on your machine, then approve the ask.
2Private networks such as 10.x, 192.168.x and intranet namesBlocked unless an allow entry names them. An unblock never opens them.
3Ports other than the proxy port list (default 80 and 443; openshell.egress.ports)Blocked.
4Your organization's block list, then its allow-only listBlocked. Nothing you do unblocks these.
5Your block list: the pack's entries plus openshell.egress.blockBlocked. An unblock does not lift it. Remove the entry.
6Your unblocksAllowed.
7The allow list (openshell.egress.allow)Allowed, and exempt from the blocklist feed.
8The blocklist feed: paste sites, anonymous file drops, webhook catchers, tunnels, anonymizersBlocked. You can unblock these.
9The profile's defaultopen allows any host name but blocks a bare IP address until you unblock it. balanced blocks anything outside its curated allowlist (you can unblock). strict has no egress proxy, so a strict sandbox never reaches this step.

Under openshell.admin.allow_unblock: false, unblocks and your allow entries do not count, and the feed is checked before your allow list. Sandbox policy lists the organization keys.

Network profiles

Every sandbox runs one policy pack. The three built-in packs are named after the network profile they set.

Settingopen (default)balancedstrict
Web accessAny site by name, except the blocklist, private networks and this machineA curated developer allowlist: package registries, source hosting, toolchains, documentationNone: only the harness's model provider
Bannernetwork: open + blocklistnetwork: allowlist (balanced)network: provider hosts only (strict)
Connection requestsDecided automaticallyTriaged, the unclear ones askedEvery one asked
Large-upload alert25 MiB10 MiB5 MiB
Your projectMounted liveMounted liveCopied
Skip-permissions modeOnOnOff: the harness keeps its prompts

--pack applies every row. --profile changes only web access, the banner and connection requests, and keeps the rest of the pack the run uses. sandbox status NAME shows both on its Policy row, for example pack open (sha256:…), network allowlist (balanced), approvals triage: the pack and its digest, the network mode with the profile in brackets, and how asks are handled. openshell.pack and openshell.profile set them for every run. On a Mac every run works on a copy whichever pack it uses.

defenseclaw sandbox run claude --pack balanced
defenseclaw sandbox run claude --profile strict

Claude Code's WebFetch asks api.anthropic.com whether each URL is safe before it fetches it. balanced and strict refuse that host, so WebFetch fails for every site. The feed says so the first time. To use WebFetch, run defenseclaw sandbox unblock api.anthropic.com --sandbox NAME or add the host to the pack's egress.allow.

The open profile is a deliberate trade-off

With open, an agent tricked by a prompt injection could send your code to any site that is not on the blocklist. The proxy sees HTTPS only as encrypted tunnels, so it cannot tell a download from an upload. For sensitive code, use balanced or strict.

Allow and block your own sites

openshell:
  egress:
    allow:
      - npm.mirror.corp.example   # an exact name or address, for an intranet host
    block:
      - files.example.net
    unblocked: []                 # written by `sandbox unblock --always`

A change reaches running sandboxes on the next config reload. Choose a policy pack covers defenseclaw sandbox policy allow and policy block.

Unblock a site

An unblock lifts blocklist-feed blocks, IP-address blocks and, with balanced, sites outside the allowlist. It never opens this machine, private networks or metadata addresses, and never overrides your block list or your organization's. A managed unblock HOST --sandbox NAME without --always lasts for that sandbox's current session only. strict has no web proxy, so there is nothing to unblock: its direct connection requests wait as asks. Unblock a site has the steps.

Asks

DefenseClaw asks you only about doors into your machine or network (a port on this machine, a private address, an intranet name) and about requests OpenShell's policy advisor flags. balanced also asks about sites outside its allowlist, and strict asks about every request. The connection that raised an ask fails at once, and the agent's next tool hook tells it the connection waits for you. After a reject, the sandbox's attempts at the same destination in the next 10 minutes are refused without a new ask.

SettingEffect on asks
approve --alwaysKeeps the decision for future sandboxes, except for your own machine and private networks, which open per sandbox only.
openshell.admin.allow_unblock: falseApprovals last for the session only and approve --always is refused.
openshell.admin.user_approvals: noneNo ask is raised.

Large uploads

The proxy counts what each sandbox sends. When a sandbox sends more than the threshold to a site it had not contacted before, DefenseClaw reports it in the feed and as a finding, and the upload goes on. To cut such uploads off, turn the block on.

openshell:
  egress:
    large_upload_mb: 10
    block_large_uploads: true

With the block on, the upload stops before the chunk that would pass the threshold, and later connections to that site are refused:

✗ files.example.net (large upload blocked: this sandbox tried to send more than 10 MiB to a destination it had not contacted before)  → unblock: defenseclaw sandbox unblock files.example.net --sandbox myapp-7f3a

Sites you unblocked or put on an allow list are exempt: uploads there are only reported. The balanced pack's own curated hosts are not exempt, so a first large push to github.com is cut too. Add such hosts to openshell.egress.allow before you turn the block on. An organization turns the block on for every sandbox with openshell.admin.block_large_uploads (sandbox policy).

What the agent is told

A plain HTTP request gets a 403 with a JSON body written for the agent (shortened):

{
  "error": "egress_blocked",
  "message": "DefenseClaw blocked sandbox egress to webhook.site:80 (webhook_catcher): Webhook catchers record every request sent to them for whoever holds the URL, a common exfiltration sink.",
  "host": "webhook.site",
  "port": 80,
  "category": "webhook_catcher",
  "source": "feed",
  "mode": "open",
  "sandbox": "myapp-7f3a",
  "unblockable": true,
  "how_to_unblock": "Tell the user DefenseClaw blocked this destination. They can allow it for this sandbox with `defenseclaw sandbox unblock webhook.site --sandbox myapp-7f3a`, for every sandbox with `defenseclaw sandbox unblock webhook.site --always`, or from the DefenseClaw activity feed. Do not try to reach it another way."
}

An HTTPS request fails at the tunnel, so tools show only an error such as curl: (56) CONNECT tunnel failed, response 403. After the shell or web-fetch tool call, DefenseClaw's hooks add a note to the harness's context that names the blocked site, why, and the unblock command, and tells the agent not to try another way. A cut large upload is reported the same way. Each block is told once, and only to the sandbox that hit it.

HarnessGets the note from the hooks
Claude Code, Codex, GitHub Copilot CLIYes
Other harnessesNo. The activity feed and your terminal report the block.

The proxy address the sandbox gets holds a user name and password of its own, so curl -v prints a Proxy-Authorization: Basic … header and env shows them in HTTPS_PROXY. The agent may warn that a credential leaked. It is not one of your secrets: DefenseClaw makes one for each sandbox, it works only on the egress proxy on this machine's loopback address, and it stops working when the sandbox is deleted.

Destinations and shadow AI

DefenseClaw lists every site each sandbox reached or tried to reach, through the proxy or around it, and says what each one is.

KindMeaning
model providerThe sandbox's model provider.
harness vendorA host of the harness's own vendor, such as Claude Code calling api.anthropic.com on a Bedrock key.
shadow AIAn AI provider in DefenseClaw's catalog that the harness does not use.
shadow AI?A host shaped like an inference endpoint. A guess.
blocked (paste site)A site that was only ever refused, with its category.
A category such as source hosting, package registryAn ordinary site.

Each shadow AI provider raises a shadow_ai finding and a ⚠ in the feed once a session: LOW the first time the policy refuses it, MEDIUM the first time the sandbox reaches it. A vendor's own website, such as developers.openai.com, is an ordinary site. Only API hosts count as AI.

⚠ shadow AI: reached api.openai.com (OpenAI)

The list survives daemon restarts and stops, and is deleted with the sandbox. defenseclaw sandbox destinations NAME prints it:

defenseclaw sandbox destinations myapp-claude on Linux with the process tree on: one shadow AI destination (api.openai.com), the model provider with its model calls, a site the blocklist refused (pastebin.com, a paste site), a source host and a package registry, each with its requests, bytes, the program that connected and its parents, and when it was last seen, and a warning that counts the shadow AI destinations

With the process tree on (--process-tree, or observe.process_tree: true in a pack), the program column also shows the connecting program's parents when one process can be identified. The optional Linux sandbox kernel feed can identify a long-running Python interpreter launched through a virtual environment or uv. Ambiguous matches show no lineage.

See what happened

CommandShows
defenseclaw sandbox activity -fThe live feed of sites, blocks, asks and findings. A burst of refusals of one site is one line, then one more a minute later that counts the repeats (and 5 more like it).
defenseclaw sandbox destinations NAMEEvery site with its kind, requests, refusals, bytes sent and the program that connected.
defenseclaw sandbox status NAMEThe Egress row: sites contacted and blocked, upstream failures, bytes, and the AI sites.
defenseclaw sandbox policy explainEach effective setting and the layer it came from: the pack, your config, a run option or your organization.

The records behind these views are in Sandbox telemetry.

Troubleshooting

The sandbox sends all traffic through DefenseClaw. These are the network failures you may see.

A tool cannot reach a site

You see: a tool fails to connect, or curl: (56) CONNECT tunnel failed, response 403.

Cause: the egress proxy blocked the site. Git over SSH and databases do not go through the web proxy.

Fix: look for the block in defenseclaw sandbox activity and unblock it. Use HTTPS remotes, or --host-port for a service on your machine.

Check: the feed shows ✓ for the site.

Git or npm fails over SSH

You see: ssh: connect to host github.com port 22: Permission denied.

Cause: no SSH leaves a sandbox, and no unblock opens it. npm resolves github:OWNER/REPO and git+ssh:// dependencies to SSH.

Fix: git remote set-url origin https://github.com/OWNER/REPO.git. Write dependencies as git+https://github.com/OWNER/REPO.git. Claude Code, Codex, Copilot CLI, Cursor and Devin agents are told this after the refused call.

Check: the git command succeeds.

Project folder mounts show as disabled

You see: the doctor's Project bind mounts check warns that mounts are off.

Cause: bind mounts are off on the Docker driver. On a Mac the doctor skips this check because every run works on a copy.

Fix: run defenseclaw sandbox doctor --fix, or setup again.

Check: the check reads enabled for the docker driver.

Model calls fail behind a TLS-inspecting proxy

You see:

  ✗ Sandbox TLS trust          TLS inspection: api.anthropic.com, api.openai.com present a certificate from "Corp Root CA", which this computer trusts but sandboxes do not, …

Cause: a proxy that decrypts TLS (Cisco Secure Access, Umbrella, Zscaler) re-signs certificates with your organization's root CA. Your computer trusts it, a sandbox does not. Two programs make a sandbox's connections: OpenShell's supervisor makes the model calls with its own trust store, which cannot be extended; everything else (package installs, git, MCP servers, web fetches) trusts the CAs you name in openshell.trusted_ca_bundle.

Fix: ask IT to exempt the model provider hosts your agents use from TLS inspection (api.anthropic.com, api.openai.com, api.githubcopilot.com, bedrock-mantle.<region>.api.aws). For everything else, save the proxy's root CA as a PEM file and name it:

defenseclaw config set openshell.trusted_ca_bundle ~/certs/proxy-root-ca.pem
defenseclaw sandbox doctor

The next run rebuilds the harness image with the CA in its system store, and each sandbox points SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS and DENO_CERT at OpenShell's bundle plus your CAs. Only the CAs in that file are added. On a managed computer your administrator sets the key. A sandbox's model provider host is open only to the agent's own programs, so a curl you run cannot reach it whatever the egress policy says.

Check: the Sandbox TLS trust check passes once the provider hosts are exempt.

The sandbox cannot upload the project copy

You see: upload the project copy: the upload to <name> did not arrive ….

Cause: OpenShell reported the upload done but the files went elsewhere, for example into another sandbox through an ssh connection shared between sandboxes.

Fix: run defenseclaw sandbox doctor and read SSH connection sharing. If your ~/.ssh/config turns on ControlMaster for Host *, add a Host sandbox block with ControlMaster no and ControlPath none above it. DefenseClaw turns sharing off for every OpenShell command it runs, so only openshell sandbox connect, upload, download or forward that you run yourself are affected.

Check: the check reads off for the OpenShell sessions DefenseClaw runs.

The ssh wrapper is refused

You see: ssh shim: DefenseClaw found no directory for an ssh with connection sharing off …, or ssh shim: <path>/ssh, the first ssh on PATH, does not keep connection sharing off ….

Cause: DefenseClaw runs OpenShell with a small ssh wrapper in a private folder in your temporary directory. It skips a temporary directory other users could change or that is mounted noexec, and falls back to ~/.defenseclaw/openshell-ssh. This error means neither worked. The second message means the first ssh on your PATH is a wrapper that adds its own ControlMaster, ControlPath, -S or -M.

Fix: point TMPDIR at a folder only you can write, on a filesystem that runs programs (mkdir -p -m 700 ~/.cache/tmp; export TMPDIR=~/.cache/tmp). Or make the wrapper pass its arguments to ssh without options of its own, or put OpenSSH's directory (the message names it, often /usr/bin) before the wrapper's on PATH. To see why ssh -G failed, run the ssh -G -o ProxyCommand=true sandbox command the message names.

Check: the SSH connection sharing check passes.