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

## Description

Headroom's published image and maintained Docker launchers could expose
the
proxy on every host interface without a proxy token. This change moves
the
security boundary to the deployment artifacts: published images default
to a
container-loopback listener, supported local launchers publish only on
host
loopback, and deliberate public deployments retain explicit token
protection.
The application factory remains transport-neutral.

Closes #3283

## Type of Change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Set both published image stages to a container-loopback default while
keeping explicit host overrides available.
- Changed native Compose and the maintained Bash and PowerShell
launchers to use an internal `0.0.0.0` listener with host-loopback
publication.
- Preserved the top-level Compose token requirement and the existing
HTTP and WebSocket credential behavior for deliberate public binds.
- Scoped differential-capture token injection to the internal
`headroom-proxy` destination and kept sensitive headers redacted in
captured records.
- Added focused launch-contract, native-core, capture, and Docker
publication checks, plus a base/head harness that tolerates a base
already containing the fix.
- Updated Docker, installer, capture, and mirrored documentation,
including an unauthenticated local loopback quickstart and an
authenticated deliberate-public example.

## Testing

- [x] Focused unit and integration tests pass
- [x] Linting and formatting checks pass
- [ ] Type checking passes
- [x] New tests added for the changed deployment and capture behavior
- [ ] Manual testing performed

### Test Output

```text
uv run python -m pytest tests/test_proxy_hardening.py tests/test_install/test_native_installers.py tests/test_docker_compose_persistence.py tests/test_network_diff_capture.py tests/test_rust_core_smoke.py -q
76 passed, 1 skipped, 1 warning in 23.45s

uv run ruff check tests/test_install/test_native_installers.py tests/test_install/test_runtime.py
All checks passed!

bash -n e2e/docker-bind-security.sh
passed

bash e2e/docker-bind-security.sh --base-image headroom-t3283-base --head-image headroom-t3283-head --fixture tests/fixtures/docker-bind-exposure.json --base-ref origin/main
base_ref=origin/main ... runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=403
docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed
```

## Real Behavior Proof

- Environment: Windows, Docker Desktop 29.6.2, current `origin/main`
base, head image, and a real Docker bridge peer.
- Exact command / steps: run the focused security/runtime tests, Compose
configuration checks, then `bash e2e/docker-bind-security.sh` against
the current base and head image definitions.
- Observed result: `76 passed, 1 skipped`; the built-image harness
passed base/head health, local completion, non-loopback isolation,
authenticated public HTTP/WebSocket controls, loopback runtime-slim
configuration, and direct Rust-core loading.
- Not tested: runtime-slim proxy service health on this host, because
its unrelated ONNXRuntime import path exits with code 139; the full
hosted matrix and a future published GHCR image remain CI-owned.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Unsafe override required: no
- Minimum rollout channel: next release containing the Docker and
launcher changes
- Stable/default behavior changed: published images and maintained local
Docker launchers now use loopback-safe publication defaults
- Kill switch / disable path: revert the deployment-artifact changes
before release; deliberate public deployments remain explicitly
operator-controlled
- Qualification impact: Docker users relying on all-interface default
publication must opt into public publication and configure the existing
proxy token
- Deliberate public deployment: use an explicit public host publication,
set `HEADROOM_PROXY_TOKEN`, and send the matching bearer or
`X-Headroom-Proxy-Token` credential
- Local deployment: use the maintained loopback publication and no
mandatory token
- Rollback path: revert the deployment-artifact and documentation
changes together

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove the behavior is effective
- [x] Focused tests pass locally with these changes
- [x] I did **not** edit `CHANGELOG.md`; release-please generates
release notes from the conventional PR title

## Additional Notes

The issue fixture remains provenance for the unauthenticated
publication. Native
`headroom proxy` defaults and the application-level authentication
owners are
unchanged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Rod Boev
2026-09-24 23:58:46 -05:00
committed by GitHub
co-authored by JerrettDavis
parent 871bbde37a
commit b0c19a25f0
26 changed files with 670 additions and 41 deletions
+5 -3
View File
@@ -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
@@ -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
+4 -4
View File
@@ -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
+1 -1
View File
@@ -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):
@@ -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
@@ -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
+2 -1
View File
@@ -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
+1 -1
View File
@@ -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
+15 -3
View File
@@ -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
+2 -1
View File
@@ -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?">
+22 -3
View File
@@ -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>
+185
View File
@@ -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"
+1 -1
View File
@@ -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`)
+8 -3
View File
@@ -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)
}
+3 -3
View File
@@ -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[@]}"
;;
*)
+1
View File
@@ -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}}
+48
View File
@@ -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
+93 -2
View File
@@ -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
+50
View File
@@ -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:
+121
View File
@@ -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"
+5
View File
@@ -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 ─────────────────────
+21
View File
@@ -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
+1 -1
View File
@@ -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
```
+15 -3
View File
@@ -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
+11
View File
@@ -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.
+23 -6
View File
@@ -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.