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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(security): reject unauthenticated public proxy binds (#3316)
Rod Boevb0c19a25f0e2
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex e3c00af68..7f42aa561 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -586,14 +586,16 @@ jobs:needs: changesif: needs.changes.outputs.native == 'true'runs-on: ubuntu-latest- timeout-minutes: 45+ timeout-minutes: 60steps:- uses: actions/checkout@v7+ with:+ fetch-depth: 0- uses: actions/setup-python@v7with: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 e2eenv:HEADROOM_DOCKER_IMAGE: headroom-native-e2e:latestdiff --git a/.github/workflows/network-diff-capture.yml b/.github/workflows/network-diff-capture.ymlindex 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 modelenv:ANTHROPIC_API_KEY: dummy+ HEADROOM_PROXY_TOKEN: capture-proofrun: docker compose -f docker/differential-network-capture/docker-compose.yml --profile run config- name: Build Claude Code runner imageenv:ANTHROPIC_API_KEY: dummy+ HEADROOM_PROXY_TOKEN: capture-proofrun: 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-capturerun: |set -euo pipefail+ HEADROOM_PROXY_TOKEN="$(openssl rand -hex 32)"+ export HEADROOM_PROXY_TOKENmkdir -p capturesdocker compose up -d --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-clienttrap 'docker compose --profile run down -v' EXITdiff --git a/Dockerfile b/Dockerfileindex 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-proxyUSER ${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 runtimeFROM runtime-slim-base AS runtimediff --git a/docker-compose.yml b/docker-compose.ymlindex 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.ymlindex 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:/mitmproxyports:- - "${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-clientCAPTURE_OUTPUT: /captures/headroom-client.jsonlCAPTURE_INCLUDE_HOSTS: ${CAPTURE_CLIENT_INCLUDE_HOSTS:-mitm-headroom-client,headroom-proxy,api.anthropic.com}+ CAPTURE_PROXY_TOKEN_HOSTS: headroom-proxyCAPTURE_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:/mitmproxyports:- - "${HEADROOM_MITM_PORT:-18081}:8080"+ - "127.0.0.1:${HEADROOM_MITM_PORT:-18081}:8080"headroom-proxy:build:@@ -84,6 +84,7 @@ services:dockerfile: Dockerfilecommand: ["--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:8080diff --git a/docker/differential-network-capture/mitm_capture.py b/docker/differential-network-capture/mitm_capture.pyindex 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 _sequencehost = flow.request.pretty_host.lower()- if INCLUDE_HOSTS and host not in INCLUDE_HOSTS:+ if not _host_is_included(host):return_sequence += 1diff --git a/docker/docker-compose.native.yml b/docker/docker-compose.native.ymlindex c999023f1..0995c3d79 100644--- a/docker/docker-compose.native.yml+++ b/docker/docker-compose.native.yml@@ -29,12 +29,13 @@ services:environment:HOME: /tmp/headroom-homeHEADROOM_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/.headroomHEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/configports:- - "${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/.headroomdiff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex 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-```bashheadroom 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 pathdiff --git a/docs/content/docs/docker-install.mdx b/docs/content/docs/docker-install.mdxindex 4fde7708a..511bcae64 100644--- a/docs/content/docs/docker-install.mdx+++ b/docs/content/docs/docker-install.mdx@@ -59,15 +59,27 @@ headroom mcp installheadroom 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:```bashdocker 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` commandsdiff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex 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.```bashdocker 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.mdxindex 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 usageheadroom 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 budgetheadroom 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=8787export 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.shnew file mode 100644index 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.txtindex 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.ps1index 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.shindex 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 argsargs+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")"${args[@]}" >/dev/null@@ -1571,8 +1571,8 @@ EOFrun_args=(docker run --rm)append_tty_args run_argsappend_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.jsonnew file mode 100644index 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.pyindex 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 dockerignoreassert "!.git/HEAD" in dockerignoreassert "!.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"]') == 2diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.pyindex 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: Pawrap_help = _run([str(wrapper), "wrap", "--help"], env=env)assert "Supported commands:" in wrap_help.stdoutassert "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: Paif 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_paif 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_calldiff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.pyindex 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.pyindex 25fb19aaf..1601cd234 100644--- a/tests/test_network_diff_capture.py+++ b/tests/test_network_diff_capture.py@@ -1,7 +1,10 @@from __future__ import annotationsimport base64+import importlib.utilimport json+import sys+import typesfrom pathlib import Pathfrom 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.pyindex 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.pyindex 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"] = originaldiff --git a/wiki/configuration.md b/wiki/configuration.mdindex aa21ea497..35684298a 100644--- a/wiki/configuration.md+++ b/wiki/configuration.md@@ -54,7 +54,7 @@ client = HeadroomClient(```bashheadroom 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.mdindex 1e0c724a1..3441a4a89 100644--- a/wiki/docker-install.md+++ b/wiki/docker-install.md@@ -56,15 +56,27 @@ headroom mcp installheadroom 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:```bashdocker 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` commandsdiff --git a/wiki/network-diff-capture.md b/wiki/network-diff-capture.mdindex 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-capturemkdir -p capturesexport 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-clientdocker 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 isthe 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.mdindex 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 usageheadroom 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 budgetheadroom 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=8787export 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.