docs(readme): document per-agent pipelock egress proxy + allowlist

Adds a short Egress section to the README explaining that agent
containers route HTTP through a per-agent pipelock sidecar on a Docker
--internal network, what the baked-in default allowlist covers, and
how to extend it via bottles.<name>.egress.allowlist with a single
JSON example. Points readers at PRD 0001 and the pipelock assessment
note for the full design and rationale.

Refs: docs/prds/0001-per-agent-egress-proxy-via-pipelock.md

Assisted-by: Claude Code
This commit is contained in:
2026-05-08 01:01:39 -04:00
parent e7e72c4833
commit 8d2110ba06
+32
View File
@@ -37,6 +37,38 @@ The container is removed automatically when the session ends. If the script
is killed with SIGKILL the exit trap won't fire and the container may be is killed with SIGKILL the exit trap won't fire and the container may be
left running; remove it with `docker rm -f <container-name>`. left running; remove it with `docker rm -f <container-name>`.
## Egress
Agent containers route HTTP / HTTPS traffic through a per-agent
[pipelock](https://github.com/luckyPipewrench/pipelock) sidecar
attached to a Docker `--internal` network. The sidecar enforces a
hostname allowlist, runs DLP scanning (48 default credential
patterns), and detects URL-embedded high-entropy secret leaks. Without
the proxy the agent has no route off-box at all — the internal network
has no default gateway. The sidecar and network are torn down with the
agent on session exit.
The effective allowlist is the union of a baked-in default for Claude
Code's required hosts (`api.anthropic.com`, `claude.ai`, ...) and the
optional `bottles.<name>.egress.allowlist` field in
`claude-bottle.json`:
```jsonc
{
"bottles": {
"default": {
"env": { },
"ssh": [ ],
"egress": { "allowlist": ["github.com"] }
}
}
}
```
The resolved allowlist is shown in the y/N preflight before launch.
See `docs/prds/0001-per-agent-egress-proxy-via-pipelock.md` for the
design and `docs/research/pipelock-assessment.md` for the rationale.
## Auth: OAuth token, not API key ## Auth: OAuth token, not API key
claude-bottle authenticates `claude` inside the container with the same claude-bottle authenticates `claude` inside the container with the same