mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## 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>
220 lines
8.2 KiB
Markdown
220 lines
8.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
|
|
```
|
|
|
|
### macOS (bash 4.3+)
|
|
|
|
```bash
|
|
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
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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
|
|
|
|
`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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
export HEADROOM_HOST_HOME="$HOME"
|
|
export HEADROOM_WORKSPACE="$PWD"
|
|
docker compose -f docker/docker-compose.native.yml up -d proxy
|
|
```
|
|
|
|
```powershell
|
|
$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][fs]
|
|
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.
|
|
|
|
[fs]: filesystem-contract.md
|
|
|
|
### macOS / Linux
|
|
|
|
```bash
|
|
export HEADROOM_HOST_HOME="$HOME"
|
|
export HEADROOM_WORKSPACE="$PWD"
|
|
docker compose -f docker/docker-compose.native.yml up proxy
|
|
```
|
|
|
|
### Windows PowerShell
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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](persistent-installs.md).
|
|
- For Docker-native `headroom install ...`, the wrapper persists its profile manifest under `~/.headroom/deploy/<profile>/`.
|