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.
| Path | What happens |
|---|---|
| Web traffic | Goes 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 calls | Go 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 else | A 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.
List view for small screens. Use the expand button to open the drawing.
- 1.Safety checksthis machine, private networks, portsblocked; no unblock opens these
- Your organization's lists
- 2.Your organization's listslisted, or off its allow-only list: blocked
- Your block list
- 3.Your block listblocked; remove the entry to open it
- Your unblocks and allow list
- 4.Your unblocks and allow listallowed
- The blocklist feed
- 5.The blocklist feedblocked; you can unblock it
- The network profile
- 6.The network profileopen, balanced or strictdecides the rest (step 9)
| Step | Check | Result |
|---|---|---|
| 1 | This machine, link-local and cloud metadata addresses | Blocked. Nothing opens them. Use --host-port PORT for one service on your machine, then approve the ask. |
| 2 | Private networks such as 10.x, 192.168.x and intranet names | Blocked unless an allow entry names them. An unblock never opens them. |
| 3 | Ports other than the proxy port list (default 80 and 443; openshell.egress.ports) | Blocked. |
| 4 | Your organization's block list, then its allow-only list | Blocked. Nothing you do unblocks these. |
| 5 | Your block list: the pack's entries plus openshell.egress.block | Blocked. An unblock does not lift it. Remove the entry. |
| 6 | Your unblocks | Allowed. |
| 7 | The allow list (openshell.egress.allow) | Allowed, and exempt from the blocklist feed. |
| 8 | The blocklist feed: paste sites, anonymous file drops, webhook catchers, tunnels, anonymizers | Blocked. You can unblock these. |
| 9 | The profile's default | open 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.
| Setting | open (default) | balanced | strict |
|---|---|---|---|
| Web access | Any site by name, except the blocklist, private networks and this machine | A curated developer allowlist: package registries, source hosting, toolchains, documentation | None: only the harness's model provider |
| Banner | network: open + blocklist | network: allowlist (balanced) | network: provider hosts only (strict) |
| Connection requests | Decided automatically | Triaged, the unclear ones asked | Every one asked |
| Large-upload alert | 25 MiB | 10 MiB | 5 MiB |
| Your project | Mounted live | Mounted live | Copied |
| Skip-permissions mode | On | On | Off: 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 strictClaude 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.
| Setting | Effect on asks |
|---|---|
approve --always | Keeps the decision for future sandboxes, except for your own machine and private networks, which open per sandbox only. |
openshell.admin.allow_unblock: false | Approvals last for the session only and approve --always is refused. |
openshell.admin.user_approvals: none | No 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: trueWith 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-7f3aSites 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.
| Harness | Gets the note from the hooks |
|---|---|
| Claude Code, Codex, GitHub Copilot CLI | Yes |
| Other harnesses | No. 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.
| Kind | Meaning |
|---|---|
model provider | The sandbox's model provider. |
harness vendor | A host of the harness's own vendor, such as Claude Code calling api.anthropic.com on a Bedrock key. |
shadow AI | An 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 registry | An 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:

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
| Command | Shows |
|---|---|
defenseclaw sandbox activity -f | The 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 NAME | Every site with its kind, requests, refusals, bytes sent and the program that connected. |
defenseclaw sandbox status NAME | The Egress row: sites contacted and blocked, upstream failures, bytes, and the AI sites. |
defenseclaw sandbox policy explain | Each 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 doctorThe 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.
Complete sandbox guide
Recipes for a sandbox you already run, including how to unblock a site, answer an ask, review, undo or pull a session, change how a run starts, and fix sandbox problems.
Policy packs and admin controls
Pick the open, balanced, or strict OpenShell sandbox policy pack, write a custom pack, and set organization-wide limits with openshell.admin.