Files
headroom/wiki/docker-install.md
ee731d7ea8 fix(proxy): refuse token-less non-loopback binds, gate operator routes (#3852)
## 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>
2026-10-05 08:27:35 -05:00

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

  1. Verifies Docker is installed and available.
  2. Pulls ghcr.io/headroomlabs-ai/headroom:latest by default, or reuses / pulls HEADROOM_DOCKER_IMAGE when you set a custom image override.
  3. Installs a headroom wrapper into ~/.local/bin or ~/bin.
  4. 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 claude
  • headroom wrap codex
  • headroom wrap aider
  • headroom wrap cursor
  • headroom wrap openclaw
  • headroom unwrap openclaw

OpenClaw remains host-native in Docker-native mode:

  • the host must already have the openclaw CLI installed
  • headroom wrap openclaw installs/configures the Headroom plugin through the host openclaw CLI
  • plugin auto-start still launches the installed host headroom wrapper from PATH, which then runs Headroom in Docker
  • local plugin source mode (--plugin-path) is also supported, but it may require host npm when 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/.headroom so 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>/.