Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(security): reject unauthenticated public proxy binds (#3316)

Rod Boevb0c19a25f0e2
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e3c00af68..7f42aa561 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -586,14 +586,16 @@ jobs:
needs: changes
if: needs.changes.outputs.native == 'true'
runs-on: ubuntu-latest
- timeout-minutes: 45
+ timeout-minutes: 60
steps:
- uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
- uses: actions/setup-python@v7
with:
python-version: "3.11"
- - name: Build local Headroom image
- run: docker build -t headroom-native-e2e:latest .
+ - name: Run Docker bind security proof
+ run: bash e2e/docker-bind-security.sh --base-image headroom-bind-base --head-image headroom-native-e2e:latest --fixture tests/fixtures/docker-bind-exposure.json --base-ref "${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}"
- name: Run Docker-native installer e2e
env:
HEADROOM_DOCKER_IMAGE: headroom-native-e2e:latest
diff --git a/.github/workflows/network-diff-capture.yml b/.github/workflows/network-diff-capture.yml
index 3d505a448..de8173b0b 100644
--- a/.github/workflows/network-diff-capture.yml
+++ b/.github/workflows/network-diff-capture.yml
@@ -64,11 +64,13 @@ jobs:
- name: Validate compose model
env:
ANTHROPIC_API_KEY: dummy
+ HEADROOM_PROXY_TOKEN: capture-proof
run: docker compose -f docker/differential-network-capture/docker-compose.yml --profile run config
- name: Build Claude Code runner image
env:
ANTHROPIC_API_KEY: dummy
+ HEADROOM_PROXY_TOKEN: capture-proof
run: docker compose -f docker/differential-network-capture/docker-compose.yml --profile run build claude-direct
- name: Smoke Claude Code runner image
@@ -117,6 +119,8 @@ jobs:
working-directory: docker/differential-network-capture
run: |
set -euo pipefail
+ HEADROOM_PROXY_TOKEN="$(openssl rand -hex 32)"
+ export HEADROOM_PROXY_TOKEN
mkdir -p captures
docker compose up -d --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-client
trap 'docker compose --profile run down -v' EXIT
diff --git a/Dockerfile b/Dockerfile
index fc2c3d176..f38f0cd7c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -185,7 +185,7 @@ RUN mkdir -p /home/nonroot /data && \
USER ${RUNTIME_USER}
WORKDIR ${RUNTIME_HOME}
-ENV HEADROOM_HOST=0.0.0.0 \
+ENV HEADROOM_HOST=127.0.0.1 \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1
@@ -202,7 +202,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD ["curl", "--fail", "--silent", "http://127.0.0.1:8787/readyz"]
ENTRYPOINT ["headroom", "proxy"]
-CMD ["--host", "0.0.0.0", "--port", "8787"]
+CMD ["--port", "8787"]
FROM ${DISTROLESS_IMAGE} AS runtime-slim
@@ -216,7 +216,7 @@ COPY --from=builder /usr/local/bin/headroom-proxy /usr/local/bin/headroom-proxy
USER ${RUNTIME_USER}
WORKDIR /app
-ENV HEADROOM_HOST=0.0.0.0 \
+ENV HEADROOM_HOST=127.0.0.1 \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONPATH=${PYTHON_SITE_PACKAGES}
@@ -227,7 +227,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD ["python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8787/readyz', timeout=5)"]
ENTRYPOINT ["python3", "-m", "headroom.cli", "proxy"]
-CMD ["--host", "0.0.0.0", "--port", "8787"]
+CMD ["--port", "8787"]
# Default published image remains python-slim runtime
FROM runtime-slim-base AS runtime
diff --git a/docker-compose.yml b/docker-compose.yml
index c4af64da9..5036ed7b2 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,7 +10,7 @@
# 3. point your LLM client at http://localhost:8787 (proxy)
#
# Just want the proxy without the memory features? You can run the proxy image
-# on its own (`docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom`); the two
+# on its own (`docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom --host 0.0.0.0 --port 8787`); the two
# database services below are only required for the memory/relevance features.
#
# Ports published on the host — all bound to 127.0.0.1 (this machine only):
diff --git a/docker/differential-network-capture/docker-compose.yml b/docker/differential-network-capture/docker-compose.yml
index 9e0ce30b6..f646b580d 100644
--- a/docker/differential-network-capture/docker-compose.yml
+++ b/docker/differential-network-capture/docker-compose.yml
@@ -25,7 +25,7 @@ services:
- ./captures:/captures
- mitm_direct_ca:/mitmproxy
ports:
- - "${DIRECT_MITM_PORT:-18080}:8080"
+ - "127.0.0.1:${DIRECT_MITM_PORT:-18080}:8080"
mitm-headroom-client:
image: mitmproxy/mitmproxy:12
@@ -43,12 +43,12 @@ services:
CAPTURE_LANE: headroom-client
CAPTURE_OUTPUT: /captures/headroom-client.jsonl
CAPTURE_INCLUDE_HOSTS: ${CAPTURE_CLIENT_INCLUDE_HOSTS:-mitm-headroom-client,headroom-proxy,api.anthropic.com}
+ CAPTURE_PROXY_TOKEN_HOSTS: headroom-proxy
CAPTURE_BODY_BYTES: ${CAPTURE_BODY_BYTES:-262144}
+ CAPTURE_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}
volumes:
- ./mitm_capture.py:/capture/mitm_capture.py:ro
- ./captures:/captures
- ports:
- - "${HEADROOM_CLIENT_MITM_PORT:-18082}:8080"
depends_on:
- headroom-proxy
@@ -76,7 +76,7 @@ services:
- ./captures:/captures
- mitm_headroom_ca:/mitmproxy
ports:
- - "${HEADROOM_MITM_PORT:-18081}:8080"
+ - "127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"
headroom-proxy:
build:
@@ -84,6 +84,7 @@ services:
dockerfile: Dockerfile
command: ["--host", "0.0.0.0", "--port", "8787", "--backend", "anthropic"]
environment:
+ HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}
ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY}
ANTHROPIC_TARGET_API_URL: ${ANTHROPIC_TARGET_API_URL:-https://api.anthropic.com}
HTTPS_PROXY: http://mitm-headroom-upstream:8080
diff --git a/docker/differential-network-capture/mitm_capture.py b/docker/differential-network-capture/mitm_capture.py
index c8e151a62..5bde6f455 100644
--- a/docker/differential-network-capture/mitm_capture.py
+++ b/docker/differential-network-capture/mitm_capture.py
@@ -20,6 +20,12 @@ INCLUDE_HOSTS = {
if host.strip()
}
BODY_BYTES = int(os.environ.get("CAPTURE_BODY_BYTES", "262144"))
+PROXY_TOKEN = os.environ.get("CAPTURE_PROXY_TOKEN") if LANE == "headroom-client" else None
+TOKEN_DESTINATION_HOSTS = {
+ host.strip().lower()
+ for host in os.environ.get("CAPTURE_PROXY_TOKEN_HOSTS", "").split(",")
+ if host.strip()
+}
SENSITIVE_HEADER_PARTS = ("authorization", "api-key", "apikey", "token", "secret", "cookie")
SENSITIVE_QUERY_PARTS = ("key", "token", "secret", "signature", "code")
_sequence = 0
@@ -53,10 +59,26 @@ def _request_json(content: bytes) -> object | None:
return None
+def _host_is_included(host: str) -> bool:
+ return not INCLUDE_HOSTS or host.lower() in INCLUDE_HOSTS
+
+
+def _destination_is_allowed(flow: http.HTTPFlow) -> bool:
+ address = getattr(getattr(flow, "server_conn", None), "address", None)
+ destination = address[0] if address else ""
+ return bool(destination) and destination.lower() in TOKEN_DESTINATION_HOSTS
+
+
+def request(flow: http.HTTPFlow) -> None:
+ """Authenticate only the internal Headroom client lane."""
+ if PROXY_TOKEN and _destination_is_allowed(flow):
+ flow.request.headers["X-Headroom-Proxy-Token"] = PROXY_TOKEN
+
+
def response(flow: http.HTTPFlow) -> None:
global _sequence
host = flow.request.pretty_host.lower()
- if INCLUDE_HOSTS and host not in INCLUDE_HOSTS:
+ if not _host_is_included(host):
return
_sequence += 1
diff --git a/docker/docker-compose.native.yml b/docker/docker-compose.native.yml
index c999023f1..0995c3d79 100644
--- a/docker/docker-compose.native.yml
+++ b/docker/docker-compose.native.yml
@@ -29,12 +29,13 @@ services:
environment:
HOME: /tmp/headroom-home
HEADROOM_HOST: 0.0.0.0
+ HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
# Canonical Headroom filesystem contract (issue #175). See `cli` service
# above for rationale.
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
ports:
- - "${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
+ - "127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
volumes:
- ${HEADROOM_WORKSPACE:-.}:/workspace
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index 69899390d..93e49cae1 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -334,7 +334,7 @@ If the upstream base URL itself must vary per request, use the `x-headroom-base-
```bash
headroom proxy \
--port 8787 \ # Port to listen on
- --host 0.0.0.0 \ # Host to bind to
+ --host 127.0.0.1 \ # Host to bind to
--mode cache \ # default; freezes prior turns for prefix-cache stability
--budget 10.00 \ # Daily budget limit in USD
--log-file headroom.jsonl # Log file path
diff --git a/docs/content/docs/docker-install.mdx b/docs/content/docs/docker-install.mdx
index 4fde7708a..511bcae64 100644
--- a/docs/content/docs/docker-install.mdx
+++ b/docs/content/docs/docker-install.mdx
@@ -59,15 +59,27 @@ headroom mcp install
headroom memory list
```
-For `proxy`, the wrapper publishes the selected port back to the host:
+For `proxy`, the maintained wrapper always publishes the selected host port on
+loopback. It passes `--host 0.0.0.0` inside the container so that the loopback
+publication can reach the container, and it has no public-publication override.
+For local-only use, no token is required:
```bash
docker run --rm -it \
- -p 8787:8787 \
+ -p 127.0.0.1:8787:8787 \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/headroomlabs-ai/headroom:latest \
- headroom proxy --host 0.0.0.0 --port 8787
+ --host 0.0.0.0 --port 8787
+```
+
+For deliberate public access, publish on an explicit public address and set
+`HEADROOM_PROXY_TOKEN`:
+
+```bash
+docker run --rm -p 0.0.0.0:8787:8787 \
+ -e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
+ ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0 --port 8787
```
### `wrap` commands
diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdx
index 5a7cd55f3..fb856fc40 100644
--- a/docs/content/docs/installation.mdx
+++ b/docs/content/docs/installation.mdx
@@ -230,7 +230,8 @@ Pre-built images are published to GitHub Container Registry on every release.
```bash
docker pull ghcr.io/headroomlabs-ai/headroom:latest
-docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest
+docker run --rm -p 127.0.0.1:8787:8787 \
+ ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0
```
<Callout type="info" title="Running Headroom without installing Python or Node?">
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index 7804f28d2..a9fa4cf33 100644
--- a/docs/content/docs/proxy.mdx
+++ b/docs/content/docs/proxy.mdx
@@ -13,8 +13,10 @@ Running a local OpenAI-compatible model? See [Local LLM prefill benchmarking](/d
# Basic usage
headroom proxy
-# Custom host and port
-headroom proxy --host 0.0.0.0 --port 8080
+# Deliberate public access, with the existing token protocol
+HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
+# Send `Authorization: Bearer replace-with-a-secret` or
+# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.
# With logging and budget
headroom proxy \
@@ -927,7 +929,9 @@ Rewriting the request body invalidates the caller's **SigV4** signature (it cove
## Environment variables
```bash
+# For deliberate public access, configure the existing token and send it from callers.
export HEADROOM_HOST=0.0.0.0
+export HEADROOM_PROXY_TOKEN='replace-with-a-secret'
export HEADROOM_PORT=8787
export HEADROOM_BUDGET=100.0
@@ -954,6 +958,8 @@ gunicorn "headroom.proxy.server:create_app()" \
--workers 4 \
--bind 0.0.0.0:8787 \
--worker-class uvicorn.workers.UvicornWorker
+# Callers must send `Authorization: Bearer replace-with-a-secret` or
+# `X-Headroom-Proxy-Token: replace-with-a-secret`.
```
`headroom.proxy.server` has no module-level `app` object — it exposes a `create_app(config: ProxyConfig | None = None) -> FastAPI` factory, so gunicorn's import string must call it.
@@ -967,9 +973,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends build-essential
&& apt-get purge -y build-essential && apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 8787
-CMD ["headroom", "proxy", "--host", "0.0.0.0"]
+CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
```
+Run this image with an explicit token and a deliberate publication choice:
+
+```bash
+docker run --rm -p 127.0.0.1:8787:8787 \
+ -e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
+ headroom-proxy
+```
+
+Callers must send `Authorization: Bearer replace-with-a-secret` or
+`X-Headroom-Proxy-Token: replace-with-a-secret`. For network access, replace
+the host-side `127.0.0.1` with an intentional public address and keep the
+token configured.
+
<Callout type="info" title="Build dependencies">
`build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension compiled from source. It is removed after installation to keep the image slim.
</Callout>
diff --git a/e2e/docker-bind-security.sh b/e2e/docker-bind-security.sh
new file mode 100644
index 000000000..f9e17a879
--- /dev/null
+++ b/e2e/docker-bind-security.sh
@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
+
+base_image=; head_image=; fixture=; base_ref="${HEADROOM_BASE_REF:-origin/main}"
+while (($#)); do
+ case "$1" in
+ --base-image) base_image="$2"; shift 2 ;;
+ --head-image) head_image="$2"; shift 2 ;;
+ --fixture) fixture="$2"; shift 2 ;;
+ --base-ref) base_ref="$2"; shift 2 ;;
+ *) echo "unknown argument: $1" >&2; exit 2 ;;
+ esac
+done
+[[ -n "$base_image" && -n "$head_image" && -n "$fixture" ]] || exit 2
+PYTHON_BIN="${PYTHON_BIN:-python3}"
+command -v "$PYTHON_BIN" >/dev/null 2>&1 || PYTHON_BIN=python
+command -v "$PYTHON_BIN" >/dev/null 2>&1 || { echo "python3 or python is required" >&2; exit 127; }
+
+base_container="headroom-bind-base-$$"; head_container="headroom-bind-head-$$"
+local_container="headroom-bind-local-$$"; public_container="headroom-bind-public-$$"
+attacker_container="headroom-bind-attacker-$$"; mock_container="headroom-bind-upstream-$$"
+slim_container="headroom-bind-slim-$$"; network="headroom-bind-network-$$"
+tmp_dir="$(mktemp -d)"
+cleanup() {
+ docker rm -f "$attacker_container" "$public_container" "$local_container" "$slim_container" "$head_container" "$base_container" "$mock_container" >/dev/null 2>&1 || true
+ # The CI workflow reuses the head image for installer, compose, and wrap checks.
+ docker image rm "$base_image" "${head_image}-runtime-slim" >/dev/null 2>&1 || true
+ docker network rm "$network" >/dev/null 2>&1 || true
+ rm -rf "$tmp_dir"
+}
+trap cleanup EXIT
+
+mapfile -t request_paths < <("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+for path in json.load(open(sys.argv[1], encoding="utf-8"))["request_paths"]:
+ print(path)
+PY
+)
+upstream_path="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["path"])
+PY
+)"
+missing_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["missing"])
+PY
+)"
+wrong_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["wrong"])
+PY
+)"
+correct_status="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["token_control"]["correct"])
+PY
+)"
+ws_status_expected="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["websocket_control"]["missing"])
+PY
+)"
+upstream_path="${upstream_path//$'\r'/}"
+
+fixture_description="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["description"])
+PY
+)"
+upstream_method="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["method"])
+PY
+)"
+upstream_authorization="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+value = json.load(open(sys.argv[1], encoding="utf-8"))["upstream"]["authorization"]
+print("" if value is None else value)
+PY
+)"
+network_publication="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["network"]["publication"])
+PY
+)"
+network_peer="$("$PYTHON_BIN" - "$fixture" <<'PY'
+import json, sys
+print(json.load(open(sys.argv[1], encoding="utf-8"))["network"]["peer"])
+PY
+)"
+
+test "$fixture_description" = "Unauthenticated public Docker publication"
+test "$upstream_method" = POST
+test -z "$upstream_authorization"
+test "$network_publication" = "0.0.0.0:8787:8787"
+test "$network_peer" = non-loopback
+git archive "$base_ref" | tar -x -C "$tmp_dir"
+docker build -t "$base_image" "$tmp_dir" >/dev/null
+docker build -t "$head_image" . >/dev/null
+slim_image="${head_image}-runtime-slim"
+docker build --target runtime-slim -t "$slim_image" . >/dev/null
+docker network create "$network" >/dev/null
+mock_script='from http.server import BaseHTTPRequestHandler,HTTPServer
+class Handler(BaseHTTPRequestHandler):
+ def _reply(self):
+ print(self.command + " " + self.path + " authorization=" + str(self.headers.get("authorization")), flush=True)
+ self.send_response(200); self.send_header("Content-Type", "application/json"); self.end_headers(); self.wfile.write(b"{}")
+ do_GET = _reply
+ do_POST = _reply
+ def log_message(self, *_): pass
+HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()'
+docker run -d --rm --name "$mock_container" --network "$network" python:3.12-alpine python -c "$mock_script" >/dev/null
+docker run -d --rm --name "$base_container" --network "$network" -p "0.0.0.0:18783:8787" \
+ -e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \
+ "$base_image" >/dev/null
+docker run -d --rm --name "$head_container" --network "$network" -p "0.0.0.0:18784:8787" "$head_image" >/dev/null
+docker run -d --rm --name "$local_container" --network "$network" -p "127.0.0.1:18786:8787" \
+ -e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \
+ "$head_image" --host 0.0.0.0 --port 8787 >/dev/null
+docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$slim_image" \
+ | grep -Fxq 'HEADROOM_HOST=127.0.0.1'
+docker run --rm --entrypoint python3 "$slim_image" -c 'import headroom._core; print("rust_core=loaded")'
+
+host_ip="$(docker network inspect -f '{{range .IPAM.Config}}{{.Gateway}}{{end}}' "$network")"
+wait_healthy() {
+ local container="$1"
+ for _ in $(seq 1 60); do
+ if docker inspect -f '{{.State.Health.Status}}' "$container" 2>/dev/null | grep -Fxq healthy; then
+ return 0
+ fi
+ sleep 1
+ done
+ docker inspect -f '{{.State.Health.Status}}' "$container"
+ docker logs "$container" 2>&1 || true
+ return 1
+}
+wait_healthy "$base_container"
+wait_healthy "$head_container"
+wait_healthy "$local_container"
+docker exec "$base_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
+docker exec "$head_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
+docker exec "$local_container" python3 -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8787/readyz", timeout=5)'
+request() {
+ local port="$1" path="$2" token="${3:-}"; local -a args=(--silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3)
+ [[ -n "$token" ]] && args+=(-H "Authorization: Bearer ${token}")
+ [[ "$path" == "$upstream_path" ]] && args+=(-H 'Content-Type: application/json' --data '{"model":"fixture","messages":[]}')
+ docker run --rm --name "$attacker_container" --network "$network" curlimages/curl:8.12.1 \
+ "${args[@]}" "http://${host_ip}:${port}${path}"
+}
+first_path="${request_paths[0]//$'\r'/}"
+base_first_status="$(request 18783 "$first_path" || true)"
+if [[ "$base_first_status" == 200 ]]; then
+ # The vulnerable base must retain the issue-shaped unauthenticated exposure.
+ for path in "${request_paths[@]}"; do
+ path="${path//$'\r'/}"
+ test "$(request 18783 "$path")" = 200
+ done
+ docker logs "$mock_container" 2>&1 | grep -Fq "${upstream_method} ${upstream_path} authorization=${upstream_authorization:-None}"
+elif [[ "$base_first_status" != 000 && "$base_first_status" != 401 && "$base_first_status" != 403 ]]; then
+ echo "unexpected safe-base status: $base_first_status" >&2
+ exit 1
+fi
+test "$(request 18784 "$first_path")" = 000
+test "$(curl --silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3 "http://127.0.0.1:18786${first_path}")" = 200
+test "$(curl --silent --output /dev/null --write-out '%{http_code}' --connect-timeout 3 --header 'Content-Type: application/json' --data '{"model":"fixture","messages":[]}' "http://127.0.0.1:18786${upstream_path}")" = 200
+test "$(request 18786 "$first_path" || true)" = 000
+token="$(openssl rand -hex 32)"
+docker run -d --rm --name "$public_container" --network "$network" -p 0.0.0.0:18785:8787 \
+ -e "HEADROOM_PROXY_TOKEN=${token}" -e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" \
+ -e OPENAI_API_KEY=upstream-secret \
+ "$head_image" --host 0.0.0.0 --port 8787 >/dev/null
+for _ in $(seq 1 60); do curl -4 --fail --silent http://127.0.0.1:18785/readyz >/dev/null && break; sleep 1; done
+for path in "${request_paths[@]}"; do
+ path="${path//$'\r'/}"
+ test "$(request 18785 "$path")" = "$missing_status"
+ test "$(request 18785 "$path" wrong-token)" = "$wrong_status"
+ test "$(request 18785 "$path" "$token")" = "$correct_status"
+done
+ws_key="$(printf '%s' 'the sample nonce' | base64 | tr -d '\n')"
+ws_status="$(docker run --rm --name "$attacker_container" --network "$network" curlimages/curl:8.12.1 --silent --output /dev/null --write-out '%{http_code}' --http1.1 -H 'Connection: Upgrade' -H 'Upgrade: websocket' -H 'Sec-WebSocket-Version: 13' -H "Sec-WebSocket-Key: ${ws_key}" "http://${host_ip}:18785/v1/live")"
+test "$ws_status" = "$ws_status_expected"
+printf 'base_ref=%s base_digest=%s head_digest=%s slim_digest=%s runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=%s\n' "$base_ref" "$(docker image inspect --format='{{.Id}}' "$base_image")" "$(docker image inspect --format='{{.Id}}' "$head_image")" "$(docker image inspect --format='{{.Id}}' "$slim_image")" "$ws_status"
+echo "docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed"
diff --git a/llms.txt b/llms.txt
index 580e1a97b..9739d354d 100644
--- a/llms.txt
+++ b/llms.txt
@@ -19,7 +19,7 @@ The canonical, always-current documentation index lives at the docs site below.
- Python: `pip install headroom-ai` (add `[all]` for every optional extra)
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
-- Docker: `docker run -p 8787:8787 ghcr.io/headroomlabs-ai/headroom:latest`
+- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`)
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index ce8282ef4..86fed772c 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -253,7 +253,7 @@ function Start-ProxyContainer {
$containerName = "headroom-proxy-$Port-$PID"
$dockerArgs = New-Object System.Collections.Generic.List[string]
- $dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName,'-p',"$Port`:$Port"))
+ $dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port"))
$dockerArgs.AddRange((Get-SharedDockerArgs))
$dockerArgs.Add($HeadroomImage)
$dockerArgs.Add('--host')
@@ -1723,7 +1723,7 @@ switch ($args[0]) {
'proxy' {
$port = 8787
$forwardArgs = New-Object System.Collections.Generic.List[string]
- foreach ($arg in $args) { $forwardArgs.Add($arg) }
+ for ($i = 1; $i -lt $args.Count; $i++) { $forwardArgs.Add($args[$i]) }
for ($i = 1; $i -lt $args.Count; $i++) {
if ($args[$i] -eq '--port' -or $args[$i] -eq '-p') {
Require-OptionValue -Arguments $args -Index $i -Option $args[$i]
@@ -1739,11 +1739,16 @@ switch ($args[0]) {
$dockerArgs = New-Object System.Collections.Generic.List[string]
$dockerArgs.AddRange([string[]]@('run','--rm'))
Add-TtyArgs -ArgsList $dockerArgs
- $dockerArgs.AddRange([string[]]@('-p',"$port`:$port"))
+ $dockerArgs.AddRange([string[]]@('-p',"127.0.0.1`:$port`:$port"))
$dockerArgs.AddRange((Get-SharedDockerArgs))
$dockerArgs.Add('--entrypoint')
$dockerArgs.Add('headroom')
$dockerArgs.Add($HeadroomImage)
+ $dockerArgs.Add('proxy')
+ $dockerArgs.Add('--host')
+ $dockerArgs.Add('0.0.0.0')
+ $dockerArgs.Add('--port')
+ $dockerArgs.Add("$port")
foreach ($arg in $forwardArgs) {
$dockerArgs.Add($arg)
}
diff --git a/scripts/install.sh b/scripts/install.sh
index b3f43cc6a..890fd3dca 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -186,7 +186,7 @@ start_proxy_container() {
local container_name="headroom-proxy-${port}-$$"
local args=()
- args=(docker run -d --rm --name "${container_name}" -p "${port}:${port}")
+ args=(docker run -d --rm --name "${container_name}" -p "127.0.0.1:${port}:${port}")
append_common_container_args args
args+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")
"${args[@]}" >/dev/null
@@ -1571,8 +1571,8 @@ EOF
run_args=(docker run --rm)
append_tty_args run_args
append_common_container_args run_args
- run_args+=(-p "${port}:${port}")
- run_args+=(--entrypoint headroom "${HEADROOM_IMAGE}" "${args[@]}")
+ run_args+=(-p "127.0.0.1:${port}:${port}")
+ run_args+=(--entrypoint headroom "${HEADROOM_IMAGE}" proxy --host 0.0.0.0 --port "${port}" "${args[@]:1}")
"${run_args[@]}"
;;
*)
diff --git a/tests/fixtures/docker-bind-exposure.json b/tests/fixtures/docker-bind-exposure.json
new file mode 100644
index 000000000..a9e0b347a
--- /dev/null
+++ b/tests/fixtures/docker-bind-exposure.json
@@ -0,0 +1 @@
+{"description":"Unauthenticated public Docker publication","request_paths":["/openapi.json","/docs","/dashboard","/v1/models","/v1/chat/completions"],"upstream":{"method":"POST","path":"/v1/chat/completions","authorization":null},"network":{"publication":"0.0.0.0:8787:8787","peer":"non-loopback"},"token_control":{"missing":401,"wrong":401,"correct":200},"websocket_control":{"missing":403}}
diff --git a/tests/test_docker_compose_persistence.py b/tests/test_docker_compose_persistence.py
index 1841fe5d2..07407e9cb 100644
--- a/tests/test_docker_compose_persistence.py
+++ b/tests/test_docker_compose_persistence.py
@@ -63,3 +63,51 @@ def test_top_level_compose_marks_source_build_version() -> None:
assert ".git/*" in dockerignore
assert "!.git/HEAD" in dockerignore
assert "!.git/refs/**" in dockerignore
+
+
+def test_native_compose_keeps_host_publication_loopback_and_optional_token() -> None:
+ compose = yaml.safe_load(
+ (ROOT / "docker" / "docker-compose.native.yml").read_text(encoding="utf-8")
+ )
+ proxy = compose["services"]["proxy"]
+
+ assert proxy["ports"] == ["127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"]
+ assert proxy["environment"]["HEADROOM_HOST"] == "0.0.0.0"
+ assert proxy["environment"]["HEADROOM_PROXY_TOKEN"] == "${HEADROOM_PROXY_TOKEN:-}"
+ assert proxy["command"] == ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]
+
+
+def test_differential_capture_compose_keeps_proxy_internal_and_host_ports_loopback() -> None:
+ compose = yaml.safe_load(
+ (ROOT / "docker" / "differential-network-capture" / "docker-compose.yml").read_text(
+ encoding="utf-8"
+ )
+ )
+ services = compose["services"]
+ assert (
+ services["headroom-proxy"]["environment"]["HEADROOM_PROXY_TOKEN"]
+ == "${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}"
+ )
+ assert (
+ services["mitm-headroom-client"]["environment"]["CAPTURE_PROXY_TOKEN"]
+ == "${HEADROOM_PROXY_TOKEN:?Set HEADROOM_PROXY_TOKEN}"
+ )
+ assert (
+ services["mitm-headroom-client"]["environment"]["CAPTURE_PROXY_TOKEN_HOSTS"]
+ == "headroom-proxy"
+ )
+ assert services["mitm-direct"]["ports"] == ["127.0.0.1:${DIRECT_MITM_PORT:-18080}:8080"]
+ assert services["mitm-headroom-upstream"]["ports"] == [
+ "127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"
+ ]
+ assert "ports" not in services["mitm-headroom-client"]
+ assert "HEADROOM_CLIENT_MITM_PORT" not in compose["services"]["mitm-headroom-client"].get(
+ "environment", {}
+ )
+
+
+def test_published_dockerfile_stages_default_to_loopback() -> None:
+ dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
+
+ assert dockerfile.count("ENV HEADROOM_HOST=127.0.0.1") == 2
+ assert dockerfile.count('CMD ["--port", "8787"]') == 2
diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.py
index 5ad549574..477bced3c 100644
--- a/tests/test_install/test_native_installers.py
+++ b/tests/test_install/test_native_installers.py
@@ -384,6 +384,39 @@ def _bash_supports_4_3() -> bool:
return (major, minor) >= (4, 3)
+def _assert_loopback_publication(call: list[str]) -> None:
+ publication = call[call.index("-p") + 1].split(":")
+ assert len(publication) == 3
+ assert publication[0] == "127.0.0.1"
+ assert publication[1] == publication[2]
+
+
+def _assert_generated_proxy_argv(
+ call: list[str], expected_port: int, forwarded_tail: list[str] | None = None
+) -> None:
+ _assert_loopback_publication(call)
+ entrypoint = call.index("--entrypoint")
+ image = entrypoint + 2
+ assert call[entrypoint + 1] == "headroom"
+ assert call[image + 1 : image + 6] == [
+ "proxy",
+ "--host",
+ "0.0.0.0",
+ "--port",
+ str(expected_port),
+ ]
+ if forwarded_tail is not None:
+ assert call[image + 6 :] == forwarded_tail
+
+
+def test_generated_wrappers_explicitly_override_image_host_for_container_access() -> None:
+ bash_source = (REPO_ROOT / "scripts" / "install.sh").read_text(encoding="utf-8")
+ powershell_source = (REPO_ROOT / "scripts" / "install.ps1").read_text(encoding="utf-8")
+
+ assert 'args+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")' in bash_source
+ assert "dockerArgs.Add('0.0.0.0')" in powershell_source
+
+
@pytest.mark.skipif(
os.name == "nt" or shutil.which("bash") is None or not _bash_supports_4_3(),
reason="installer requires bash >= 4.3 (macOS system bash is 3.2)",
@@ -407,6 +440,7 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
wrap_help = _run([str(wrapper), "wrap", "--help"], env=env)
assert "Supported commands:" in wrap_help.stdout
assert "copilot" not in wrap_help.stdout
+ _run([str(wrapper), "proxy", "--help"], env=env)
unsupported_wrap = _run(
[str(wrapper), "wrap", "copilot", "--help"],
env=env,
@@ -517,8 +551,33 @@ def test_bash_native_installer_supports_persistent_docker_lifecycle(tmp_path: Pa
if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "--help" in call
)
assert "-it" not in help_call
+ proxy_help_call = next(
+ call
+ for call in docker_calls
+ if call[:2] == ["run", "--rm"] and "-p" in call and "proxy" in call and "--help" in call
+ )
+ _assert_generated_proxy_argv(proxy_help_call, 8787)
+ explicit_port = _free_port()
+ _run(
+ [str(wrapper), "proxy", "--port", str(explicit_port), "--host", "192.0.2.1"],
+ env=env,
+ )
+ explicit_call = next(
+ call
+ for call in reversed(_read_fake_docker_log(env))
+ if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "192.0.2.1" in call
+ )
+ _assert_generated_proxy_argv(
+ explicit_call,
+ explicit_port,
+ ["--port", str(explicit_port), "--host", "192.0.2.1"],
+ )
install_call = next(
- call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
+ call
+ for call in docker_calls
+ if call[:2] == ["run", "-d"]
+ and "--name" in call
+ and call[call.index("--name") + 1] == "headroom-smoke"
)
assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
@@ -1040,8 +1099,40 @@ def test_powershell_native_installer_supports_persistent_docker_lifecycle(tmp_pa
if call[:2] == ["run", "--rm"] and "-p" in call and "proxy" in call and "--help" in call
)
assert "-it" not in proxy_help_call
+ _assert_generated_proxy_argv(proxy_help_call, 8787)
+ explicit_port = _free_port()
+ _run(
+ [
+ powershell,
+ "-NoProfile",
+ "-ExecutionPolicy",
+ "Bypass",
+ "-File",
+ str(wrapper),
+ "proxy",
+ "--port",
+ str(explicit_port),
+ "--host",
+ "192.0.2.1",
+ ],
+ env=env,
+ )
+ explicit_call = next(
+ call
+ for call in reversed(_read_fake_docker_log(env))
+ if call[:2] == ["run", "--rm"] and "--entrypoint" in call and "192.0.2.1" in call
+ )
+ _assert_generated_proxy_argv(
+ explicit_call,
+ explicit_port,
+ ["--port", str(explicit_port), "--host", "192.0.2.1"],
+ )
install_call = next(
- call for call in docker_calls if call[:2] == ["run", "-d"] and "--name" in call
+ call
+ for call in docker_calls
+ if call[:2] == ["run", "-d"]
+ and "--name" in call
+ and call[call.index("--name") + 1] == "headroom-smoke"
)
assert install_call[install_call.index("-p") + 1] == f"127.0.0.1:{port}:{port}"
assert "/tmp/headroom-home/.headroom/memory.db" in install_call
diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py
index 21b60cc48..1c684506c 100644
--- a/tests/test_install/test_runtime.py
+++ b/tests/test_install/test_runtime.py
@@ -106,6 +106,56 @@ def test_build_runtime_command_for_docker_includes_deployment_env(
assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command
+def test_build_runtime_command_preserves_non_ascii_ambient_token(
+ monkeypatch, tmp_path: Path
+) -> None:
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
+ token = "tökén-安全-🔐"
+ monkeypatch.setenv("HEADROOM_PROXY_TOKEN", token)
+ manifest = DeploymentManifest(
+ profile="default",
+ preset="persistent-docker",
+ runtime_kind="docker",
+ supervisor_kind="none",
+ scope="user",
+ provider_mode="manual",
+ targets=["claude"],
+ port=8787,
+ host="127.0.0.1",
+ backend="anthropic",
+ image="ghcr.io/headroomlabs-ai/headroom:latest",
+ base_env={"HEADROOM_PORT": "8787"},
+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+ )
+
+ command = build_runtime_command(manifest)
+
+ token_env_index = command.index("HEADROOM_PROXY_TOKEN")
+ assert command[token_env_index - 1] == "--env"
+ assert token not in command
+
+ captured: dict[str, list[str] | dict[str, str]] = {}
+
+ def fake_run(command: list[str], **kwargs: object) -> None:
+ captured["command"] = command
+ container_env: dict[str, str] = {}
+ for index, arg in enumerate(command):
+ if arg != "--env":
+ continue
+ value = command[index + 1]
+ if "=" in value:
+ name, resolved = value.split("=", 1)
+ container_env[name] = resolved
+ else:
+ container_env[value] = os.environ[value]
+ captured["container_env"] = container_env
+
+ monkeypatch.setattr("headroom.install.runtime.subprocess.run", fake_run)
+ start_persistent_docker(manifest)
+ assert captured["container_env"]["HEADROOM_PROXY_TOKEN"] == token
+ assert token not in captured["command"]
+
+
def test_build_runtime_command_for_docker_includes_gpu_passthrough(
monkeypatch, tmp_path: Path
) -> None:
diff --git a/tests/test_network_diff_capture.py b/tests/test_network_diff_capture.py
index 25fb19aaf..1601cd234 100644
--- a/tests/test_network_diff_capture.py
+++ b/tests/test_network_diff_capture.py
@@ -1,7 +1,10 @@
from __future__ import annotations
import base64
+import importlib.util
import json
+import sys
+import types
from pathlib import Path
from click.testing import CliRunner
@@ -22,6 +25,124 @@ def _body(payload: dict[str, object]) -> str:
return base64.b64encode(json.dumps(payload).encode("utf-8")).decode("ascii")
+class _Headers(dict[str, str]):
+ def items(self, multi: bool = False):
+ return super().items()
+
+
+def _load_capture_addon(
+ monkeypatch,
+ tmp_path: Path,
+ lane: str,
+ token: str | None,
+ *,
+ include_hosts: str = "api.anthropic.com",
+ token_hosts: str = "headroom-proxy",
+):
+ fake_http = types.SimpleNamespace(HTTPFlow=object)
+ fake_mitmproxy = types.ModuleType("mitmproxy")
+ fake_mitmproxy.http = fake_http
+ monkeypatch.setitem(sys.modules, "mitmproxy", fake_mitmproxy)
+ monkeypatch.setenv("CAPTURE_LANE", lane)
+ monkeypatch.setenv("CAPTURE_INCLUDE_HOSTS", include_hosts)
+ monkeypatch.setenv("CAPTURE_PROXY_TOKEN_HOSTS", token_hosts)
+ monkeypatch.setenv("CAPTURE_OUTPUT", str(tmp_path / f"{lane}.jsonl"))
+ if token is None:
+ monkeypatch.delenv("CAPTURE_PROXY_TOKEN", raising=False)
+ else:
+ monkeypatch.setenv("CAPTURE_PROXY_TOKEN", token)
+
+ path = Path(__file__).parents[1] / "docker/differential-network-capture/mitm_capture.py"
+ spec = importlib.util.spec_from_file_location(f"mitm_capture_{lane}", path)
+ assert spec and spec.loader
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_network_capture_injects_token_only_on_included_headroom_client_lane(
+ monkeypatch, tmp_path: Path
+) -> None:
+ token = "capture-secret"
+ headroom_addon = _load_capture_addon(monkeypatch, tmp_path, "headroom-client", token)
+ headroom_flow = types.SimpleNamespace(
+ request=types.SimpleNamespace(
+ headers=_Headers(),
+ pretty_host="api.anthropic.com",
+ pretty_url="https://api.anthropic.com/v1/messages",
+ method="POST",
+ raw_content=b"{}",
+ ),
+ server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
+ response=types.SimpleNamespace(
+ headers=_Headers({"X-Headroom-Proxy-Token": token}),
+ raw_content=b"{}",
+ status_code=200,
+ ),
+ )
+
+ headroom_addon.request(headroom_flow)
+
+ assert headroom_flow.request.headers == {"X-Headroom-Proxy-Token": token}
+ headroom_addon.response(headroom_flow)
+ record = json.loads((tmp_path / "headroom-client.jsonl").read_text(encoding="utf-8"))
+ assert record["request_headers"]["X-Headroom-Proxy-Token"] == "<redacted>"
+ assert record["response_headers"]["X-Headroom-Proxy-Token"] == "<redacted>"
+
+ outside_flow = types.SimpleNamespace(
+ request=types.SimpleNamespace(
+ headers=_Headers(),
+ pretty_host="other.example.com",
+ ),
+ server_conn=types.SimpleNamespace(address=("other.example.com", 443)),
+ )
+
+ headroom_addon.request(outside_flow)
+
+ assert outside_flow.request.headers == {}
+
+ direct_addon = _load_capture_addon(monkeypatch, tmp_path, "direct", token)
+ direct_flow = types.SimpleNamespace(
+ request=types.SimpleNamespace(
+ headers=_Headers(),
+ pretty_host="api.anthropic.com",
+ ),
+ server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
+ )
+
+ direct_addon.request(direct_flow)
+
+ assert direct_flow.request.headers == {}
+
+
+def test_network_capture_token_destination_allowlist_is_independent_of_logging_filter(
+ monkeypatch, tmp_path: Path
+) -> None:
+ addon = _load_capture_addon(
+ monkeypatch,
+ tmp_path,
+ "headroom-client",
+ "capture-secret",
+ include_hosts="other.example.com",
+ )
+ flow = types.SimpleNamespace(
+ request=types.SimpleNamespace(headers=_Headers(), pretty_host="api.anthropic.com"),
+ server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
+ )
+ addon.request(flow)
+ assert flow.request.headers == {"X-Headroom-Proxy-Token": "capture-secret"}
+
+ empty_allowlist = _load_capture_addon(
+ monkeypatch, tmp_path, "headroom-client", "capture-secret", token_hosts=""
+ )
+ empty_flow = types.SimpleNamespace(
+ request=types.SimpleNamespace(headers=_Headers(), pretty_host="api.anthropic.com"),
+ server_conn=types.SimpleNamespace(address=("headroom-proxy", 8787)),
+ )
+ empty_allowlist.request(empty_flow)
+ assert empty_flow.request.headers == {}
+
+
def test_network_diff_redacts_and_reports_body_json_deltas(tmp_path: Path) -> None:
direct_path = tmp_path / "direct.jsonl"
headroom_path = tmp_path / "headroom.jsonl"
diff --git a/tests/test_proxy_hardening.py b/tests/test_proxy_hardening.py
index 06221cc8d..9542db6cf 100644
--- a/tests/test_proxy_hardening.py
+++ b/tests/test_proxy_hardening.py
@@ -37,6 +37,11 @@ def _make_app(**overrides):
return create_app(config)
+def test_create_app_accepts_test_net_host_without_transport_validation() -> None:
+ app = _make_app(host="203.0.113.5", proxy_token=None)
+ assert app is not None
+
+
# ───────────────────────────── 2.1 inbound auth token ─────────────────────
diff --git a/tests/test_rust_core_smoke.py b/tests/test_rust_core_smoke.py
index e45d5461c..d2ff6f4aa 100644
--- a/tests/test_rust_core_smoke.py
+++ b/tests/test_rust_core_smoke.py
@@ -177,3 +177,24 @@ def test_check_rust_core_returns_loaded_when_extension_present(
status, error = server._check_rust_core()
assert status == "loaded"
assert error is None
+
+
+def test_proxy_refuses_marker_mismatch(monkeypatch: pytest.MonkeyPatch) -> None:
+ """A loadable but stale extension is still a required-core failure."""
+ import sys
+ from types import SimpleNamespace
+
+ from headroom.proxy import server
+
+ monkeypatch.delenv("HEADROOM_REQUIRE_RUST_CORE", raising=False)
+ original = sys.modules.get("headroom._core")
+ sys.modules["headroom._core"] = SimpleNamespace(hello=lambda: "stale-core")
+ try:
+ with pytest.raises(SystemExit) as exc_info:
+ server._check_rust_core()
+ assert exc_info.value.code == 78
+ finally:
+ if original is None:
+ sys.modules.pop("headroom._core", None)
+ else:
+ sys.modules["headroom._core"] = original
diff --git a/wiki/configuration.md b/wiki/configuration.md
index aa21ea497..35684298a 100644
--- a/wiki/configuration.md
+++ b/wiki/configuration.md
@@ -54,7 +54,7 @@ client = HeadroomClient(
```bash
headroom proxy \
--port 8787 \ # Port to listen on
- --host 0.0.0.0 \ # Host to bind to
+ --host 127.0.0.1 \ # Host to bind to
--budget 10.00 \ # Daily budget limit in USD
--log-file headroom.jsonl # Log file path
```
diff --git a/wiki/docker-install.md b/wiki/docker-install.md
index 1e0c724a1..3441a4a89 100644
--- a/wiki/docker-install.md
+++ b/wiki/docker-install.md
@@ -56,15 +56,27 @@ headroom mcp install
headroom memory list
```
-For `proxy`, the wrapper publishes the selected port back to the host:
+For `proxy`, the maintained wrapper always publishes the selected host port on
+loopback. It passes `--host 0.0.0.0` inside the container so that the loopback
+publication can reach the container, and it has no public-publication override.
+For local-only use, no token is required:
```bash
docker run --rm -it \
- -p 8787:8787 \
+ -p 127.0.0.1:8787:8787 \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/headroomlabs-ai/headroom:latest \
- headroom proxy --host 0.0.0.0 --port 8787
+ --host 0.0.0.0 --port 8787
+```
+
+For deliberate public access, publish on an explicit public address and set
+`HEADROOM_PROXY_TOKEN`:
+
+```bash
+docker run --rm -p 0.0.0.0:8787:8787 \
+ -e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
+ ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0 --port 8787
```
### `wrap` commands
diff --git a/wiki/network-diff-capture.md b/wiki/network-diff-capture.md
index 073133814..ce32cbc0a 100644
--- a/wiki/network-diff-capture.md
+++ b/wiki/network-diff-capture.md
@@ -12,6 +12,7 @@ and JSON payload differences.
cd docker/differential-network-capture
mkdir -p captures
export ANTHROPIC_API_KEY=...
+export HEADROOM_PROXY_TOKEN='capture-secret'
export CLAUDE_PROMPT="Summarize this repository in one sentence."
docker compose up --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-client
docker compose --profile run run --rm claude-direct
@@ -27,6 +28,16 @@ The Headroom lane also writes
`docker/differential-network-capture/captures/headroom-upstream.jsonl`, which is
the request Headroom forwards to Anthropic after proxy processing.
+`HEADROOM_PROXY_TOKEN` is required for the Headroom lane. The capture addon
+adds it only to requests from `mitm-headroom-client`; direct and upstream
+captures never receive it. Keep this value private and use the same value when
+calling a deliberately public Headroom proxy.
+
+The direct and upstream mitmproxy ports are published on loopback for local
+inspection. The client capture stays on the internal Compose network because
+it is an internal hop, so `HEADROOM_CLIENT_MITM_PORT` is intentionally not a
+supported setting.
+
By default only `api.anthropic.com` is logged. Override
`CAPTURE_INCLUDE_HOSTS` with a comma-separated list to include other hosts.
diff --git a/wiki/proxy.md b/wiki/proxy.md
index 69d3f558c..5d56ccff1 100644
--- a/wiki/proxy.md
+++ b/wiki/proxy.md
@@ -10,13 +10,13 @@ The Headroom proxy server is a production-ready HTTP server that applies context
# Basic usage
headroom proxy
-# Custom port
-headroom proxy --port 8080
+# Deliberate public access, with the existing token protocol
+HEADROOM_PROXY_TOKEN='replace-with-a-secret' headroom proxy --host 0.0.0.0 --port 8080
+# Send `Authorization: Bearer replace-with-a-secret` or
+# `X-Headroom-Proxy-Token: replace-with-a-secret` from the caller.
-# With all options
+# With logging and budget
headroom proxy \
- --host 0.0.0.0 \
- --port 8787 \
--log-file /var/log/headroom.jsonl \
--budget 100.0
```
@@ -427,7 +427,9 @@ headroom_latency_ms_sum
## Configuration via Environment
```bash
+# For deliberate public access, configure the existing token and send it from callers.
export HEADROOM_HOST=0.0.0.0
+export HEADROOM_PROXY_TOKEN='replace-with-a-secret'
export HEADROOM_PORT=8787
export HEADROOM_BUDGET=100.0
@@ -455,6 +457,8 @@ gunicorn headroom.proxy.server:create_app \
--bind 0.0.0.0:8787 \
--worker-class uvicorn.workers.UvicornWorker \
--factory
+# Callers must send `Authorization: Bearer replace-with-a-secret` or
+# `X-Headroom-Proxy-Token: replace-with-a-secret`.
```
Or with Docker:
@@ -466,7 +470,20 @@ RUN apt-get update && apt-get install -y --no-install-recommends build-essential
&& apt-get purge -y build-essential && apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 8787
-CMD ["headroom", "proxy", "--host", "0.0.0.0"]
+CMD ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
```
+Run this image with an explicit token and a deliberate publication choice:
+
+```bash
+docker run --rm -p 127.0.0.1:8787:8787 \
+ -e HEADROOM_PROXY_TOKEN='replace-with-a-secret' \
+ headroom-proxy
+```
+
+Callers must send `Authorization: Bearer replace-with-a-secret` or
+`X-Headroom-Proxy-Token: replace-with-a-secret`. For network access, replace
+the host-side `127.0.0.1` with an intentional public address and keep the
+token configured.
+
> **Note:** `build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension that must be compiled from source. It is removed after installation to keep the image slim.