## Why Four related gaps in the proxy's network gate (findings 01-F1, 01-F2, 01-F5, 01-F9): - **Open bind.** A non-loopback bind with no `HEADROOM_PROXY_TOKEN` only logged a warning, then served the `/v1/*` relay, with the operator's upstream credentials, to every peer that could reach the port. - **Missing peer address.** `is_loopback_host(None)` returned `True`. A Unix-domain socket, an ASGI adapter that leaves `scope["client"]` unset, or a hand-built request therefore turned off the token gate, the `/admin` and `/debug` guards and the WebSocket gate. - **Operator data routes.** `/stats-history` (including CSV export), `/quota`, `/subscription-window` and `/metrics` were served to any network caller. - **WebSocket loopback exemption** checked only the peer IP, not the `Host` header, so it had no DNS-rebinding defence. ## What changes - New `headroom/proxy/bind_policy.py`. A non-loopback bind (`0.0.0.0`, `::`, a LAN address or a hostname) with no token is refused at three places: `create_app` (embedders and the multi-worker factory), `run_server` (one exit with code 2 before uvicorn forks) and the `headroom proxy` CLI (a clear error before the banner, exit code 1). An absent host means uvicorn's default `127.0.0.1`. - `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` acknowledges an open bind when the runtime already restricts reachability, such as a container published on `127.0.0.1`. The `proxy_open_bind` warning is still logged on that path, and the banner says the bind is open. - `is_loopback_host(None)` now returns `False` (fail closed), matching `identity.py`. - `/stats-history`, `/quota` and `/subscription-window` answer only: a non-loopback caller that passed the token gate, a loopback caller (peer and `Host` header both loopback), a trusted dashboard client, or, under an acknowledged token-less bind, the container's own default-gateway TCP peer with a loopback `Host` (the host browser reaching a `127.0.0.1`-published container). Everyone else gets 404, as with `/admin`. Settings writes keep their stricter rule with no token short-cut. - `/metrics` answers a non-loopback caller that passed the token gate, a loopback caller, a connecting peer in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` (whatever it forwards), or a resolved client in the dashboard CIDRs. For CIDR peers a hostname `Host` is fine, so Prometheus scrapers work; a cross-origin browser request is still refused. - The token short-cut applies only to non-loopback requests. The gate exempts loopback peers without checking `Host`, so a loopback request has not proven it holds the token and must pass the loopback `Host` check. This blocks a DNS-rebound browser on the operator's machine. - The `/dashboard` shell stays ungated. It is a static template, like the already public `/dashboard/static` assets. Gating it would break the dashboard for containers published on host loopback, where the peer is the bridge gateway and `Host` is `localhost`. The data routes behind it are gated. - The WebSocket loopback exemption requires a loopback peer and a loopback `Host` header. A loopback peer with a foreign `Host` can still connect with the token. - Launchers that always publish on `127.0.0.1` set the acknowledgement themselves: `headroom install` (docker preset), `scripts/install.sh` and `scripts/install.ps1` (through one helper that adds the acknowledgement only together with the `127.0.0.1` publication), and `docker/docker-compose.native.yml`. - Docs: `proxy.mdx` documents the new variable and which routes the token also gates; `docker-install` (docs and wiki) and the `docker-compose.yml` comment show the acknowledgement in the loopback-published example. `e2e/docker-bind-security.sh` sets it and checks that the same launch without it refuses to start. ## Behaviour change (breaking) - `headroom proxy --host 0.0.0.0`, or `HEADROOM_HOST` set to any non-loopback address, without `HEADROOM_PROXY_TOKEN` now refuses to start. The error names both remedies. Set a token, bind loopback, or set `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` when the port is already confined. Anyone running the image by hand with `--host 0.0.0.0` and no token must add one of these. - Without a token, `/stats-history`, `/quota`, `/subscription-window` and `/metrics` return 404 to non-loopback callers outside a trusted CIDR. Prometheus scrapers on another host must be in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` or send the token. - Code that relied on a request with no peer address being treated as loopback now gets the non-loopback path. - The default loopback run is unchanged. ## Tests - `tests/test_proxy_bind_policy.py`: the refuse/allow matrix (non-loopback, loopback, unset host, token, acknowledgement values), the warning on the acknowledged path, `create_app`, the `run_server` exit before uvicorn, and the CLI (refusal, `HEADROOM_HOST` from env, acknowledged start, offline banner, start with a token). - `tests/test_proxy_loopback_gating.py`: each data route against non-loopback, loopback, trusted-CIDR and token callers; the dashboard shell stays reachable; the host of an acknowledged, loopback-published container reads the data routes while another bridge peer, a forwarded gateway address and a foreign `Host` do not; CSV export is not served to network callers; `/metrics` across loopback, both CIDR lists, out-of-range peers, cross-origin browsers and token callers, including a trusted gateway relaying a scraper outside its own range. A regression test shows that a token on the proxy does not exempt a loopback peer from the `Host` check; it fails without the fix. - `tests/test_proxy_hardening.py`: the HTTP gate with no peer address, WebSocket `Host` cases, `require_loopback` and `/debug` with no peer. - Installer tests: `headroom install` adds the acknowledgement, and the shell and PowerShell wrappers add it only together with the loopback publication. Launcher-level tests start the proxy with the environment and `--host` that `build_runtime_command()` and `docker-compose.native.yml` produce and check that the host browser (bridge-gateway peer) gets `/stats-history` and another container does not. - Tests that bound `0.0.0.0` for unrelated reasons now set a token or the acknowledgement. Tests that read operator routes use an explicit loopback peer. On `main`, 14 of the gating and hardening tests fail and the bind-policy module does not exist. Manual runs: token-less `--host 0.0.0.0` exits with the refusal from both the CLI and `run_server`; with the acknowledgement, the data routes are 404 to a LAN peer and to a loopback peer with a foreign `Host`; with a token, a LAN peer gets 401 without it and 200 with it; the default loopback bind starts as before. Not tested: a real Unix-domain-socket deployment and a real Prometheus scrape (both covered by tests only). ## Merge order Part of a set. Suggested order: #3852 → #3891 → #3849 → #3860 → #3862 → #3863. This PR goes first: it is the gate the others assume, and it is the release-note event. ## Not in this PR - Enforcing the token for loopback callers when one is configured. Revised 2026-10-02 after review: `/metrics` matches gateway CIDRs against the TCP peer, and the operator data routes serve the host of a loopback-published container (bridge-gateway peer under the launchers' bind acknowledgement) so the default Docker dashboard works. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3852" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
8.2 KiB
Docker-Native Install
Run Headroom without installing Python or Node.js on the host. The install scripts add a native headroom wrapper that keeps Headroom itself in Docker while orchestrating the rest of your workflow on the host OS.
One-line install
Linux
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
macOS (bash 4.3+)
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | "$(brew --prefix bash)/bin/bash"
Stock /bin/bash on macOS is 3.2, so install a newer bash first (for example via Homebrew) and run the installer with that shell. The installed wrapper pins that same bash interpreter so later invocations stay on the supported runtime.
Windows PowerShell
irm https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.ps1 | iex
What the installer does
- Verifies Docker is installed and available.
- Pulls
ghcr.io/headroomlabs-ai/headroom:latestby default, or reuses / pullsHEADROOM_DOCKER_IMAGEwhen you set a custom image override. - Installs a
headroomwrapper into~/.local/binor~/bin. - Updates shell startup files so the wrapper directory is on
PATH.
The wrapper keeps Headroom inside Docker and mounts host state back into the container so native behavior stays consistent:
- project workspace ->
/workspace ~/.headroom~/.claude~/.codex~/.gemini
Port 8787 stays the default, so http://localhost:8787 works the same way as a native install.
Published releases also push versioned GHCR tags such as ghcr.io/headroomlabs-ai/headroom:0.35.0, and those images are built with the same synced package version used for the matching PyPI and npm release.
How the wrapper behaves
Native Headroom commands
These run directly inside the container:
headroom proxy
headroom learn
headroom mcp install
headroom memory list
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 needed, but the proxy refuses to start on a
non-loopback bind without one unless you acknowledge that the runtime already
restricts who can reach the port (here: the 127.0.0.1 publication):
docker run --rm -it \
-p 127.0.0.1:8787:8787 \
-e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 \
-v "$PWD:/workspace" \
-w /workspace \
ghcr.io/headroomlabs-ai/headroom:latest \
--host 0.0.0.0 --port 8787
The maintained wrappers (headroom install, the install.sh / install.ps1
native wrappers, and docker/docker-compose.native.yml) set that acknowledgement
themselves, and only together with the 127.0.0.1 publication it depends on.
For deliberate public access, publish on an explicit public address and set
HEADROOM_PROXY_TOKEN:
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
wrap is host-oriented in Docker-native mode:
- the wrapper starts the Headroom proxy in Docker
- container-side prep writes Headroom config and memory into mounted host files
- the target CLI itself is launched on the host by the wrapper
Supported host wrap flows:
headroom wrap claudeheadroom wrap codexheadroom wrap aiderheadroom wrap cursorheadroom wrap openclawheadroom unwrap openclaw
OpenClaw remains host-native in Docker-native mode:
- the host must already have the
openclawCLI installed headroom wrap openclawinstalls/configures the Headroom plugin through the hostopenclawCLI- plugin auto-start still launches the installed host
headroomwrapper fromPATH, which then runs Headroom in Docker - local plugin source mode (
--plugin-path) is also supported, but it may require hostnpmwhen build steps are needed
Persistent Docker lifecycle from the native wrapper
The Docker-native headroom wrapper now exposes the persistent Docker lifecycle directly:
headroom install apply --profile default --preset persistent-docker
headroom install status
headroom install restart
headroom install remove
In Docker-native mode this surface is intentionally scoped to persistent-docker:
- supported:
apply,status,start,stop,restart,remove - supported flags:
--profile,--port,--backend,--anyllm-provider,--region,--mode,--memory,--no-telemetry,--image - not supported:
persistent-service,persistent-task, or provider/user/system mutation flags such as--scope,--providers, and--target
Those broader lifecycle and config-mutation flows still belong to the Python-native headroom install ... command.
Persistent Docker deployments launched by the wrapper also tag the proxy process with deployment metadata, so /health reports the active profile, preset, runtime, supervisor, and scope the same way the Python install subsystem does.
Docker Compose support
Use docker/docker-compose.native.yml when you want an explicit compose-managed proxy or CLI shell, or when you prefer compose over the native wrapper's headroom install ... surface.
Persistent Docker runtime
The proxy service now uses restart: unless-stopped, so compose can act as the always-on Docker runtime for Headroom:
export HEADROOM_HOST_HOME="$HOME"
export HEADROOM_WORKSPACE="$PWD"
docker compose -f docker/docker-compose.native.yml up -d proxy
$env:HEADROOM_HOST_HOME = $HOME
$env:HEADROOM_WORKSPACE = (Get-Location).Path
docker compose -f docker/docker-compose.native.yml up -d proxy
This remains a supported persistent-Docker path when you want the proxy managed explicitly through Compose instead of the installed wrapper.
HEADROOM_WORKSPACE vs HEADROOM_WORKSPACE_DIR
These are two different variables — both are set by the compose file, and both are retained for backward compatibility:
HEADROOM_WORKSPACE(host-side) is the directory the compose file bind-mounts into the container as/workspace. It behaves like CWD in a native (non-Docker) run.HEADROOM_WORKSPACE_DIR(inside-the-container) is the canonical Headroom state root — part of the filesystem contract introduced in issue #175. The compose file sets it to/tmp/headroom-home/.headroomso the proxy resolves savings, logs, TOIN, and memory under the bind-mounted${HOME}/.headroom.
You do not need to set HEADROOM_WORKSPACE_DIR manually when using the
shipped compose file — it is already in the environment: block.
macOS / Linux
export HEADROOM_HOST_HOME="$HOME"
export HEADROOM_WORKSPACE="$PWD"
docker compose -f docker/docker-compose.native.yml up proxy
Windows PowerShell
$env:HEADROOM_HOST_HOME = $HOME
$env:HEADROOM_WORKSPACE = (Get-Location).Path
docker compose -f docker/docker-compose.native.yml up proxy
You can also run one-off CLI commands through compose:
docker compose -f docker/docker-compose.native.yml run --rm cli learn
docker compose -f docker/docker-compose.native.yml run --rm cli mcp install
Environment passthrough
The wrapper forwards Headroom and provider environment variables into the container, including common prefixes such as:
HEADROOM_ANTHROPIC_OPENAI_GEMINI_AWS_GOOGLE_/GOOGLE_CLOUD_AZURE_OTEL_
That keeps provider auth and runtime config working without maintaining a separate env file for the container.
Notes
- Docker is the only required Headroom runtime dependency on the host.
- Wrapped tools like Claude Code, Codex CLI, Aider, and Cursor still run on the host when you use
headroom wrap .... - The install scripts are idempotent: rerunning them refreshes the wrapper and image without duplicating shell profile blocks.
- For persistent service and task installs, use the Python-native
headroom install ...workflow described in Persistent Installs. - For Docker-native
headroom install ..., the wrapper persists its profile manifest under~/.headroom/deploy/<profile>/.