Headroom

Headroom is an optional Python compression proxy. When it is enabled and reachable, DurinDoor sends eligible source-format chat requests to it before translation. When it is down or the call fails, the gateway continues uncompressed.

Open Dashboard → Headroom (/dashboard/headroom) for the proxy UI. Start, stop, extras, and timeout live on Dashboard → Token Saver → Settings (/dashboard/token-saver/settings). Token totals are on Dashboard → Token Saver → Statistics.

headroomEnabled defaults to false. headroomUrl defaults to HEADROOM_URL or http://localhost:8787. headroomCompressUserMessages defaults to false (tool results and similar blocks are the usual target). headroomTimeoutMs defaults to 15000. The settings API accepts whole milliseconds from 1000 through 120000. Invalid values that reach the compression layer fail safe to 15000.

Headroom makes one proxy call. It rejects CCR markers, explicit error-tool results, reordered or identity-changing OpenAI messages, skipped/no-gain/conflicting token results, and candidates that shrink the serialized request by five percent or less.

Prepare Python

headroom-ai requires Python 3.10 or newer. There is no upper bound.

DurinDoor installs these extras by default: proxy (the HTTP compression proxy), code (Tree-sitter AST compression), ml (Kompress-v2). Auto-configure asks for headroom-ai[proxy,code,ml].

Install and start the managed proxy

DurinDoor owns ${DATA_DIR}/headroom/venv (plus proxy.pid, proxy.log, install.log, and events.jsonl next to it). Default DATA_DIR is ~/.9router. The service uses this venv so it does not depend on a user ~/.local install and does not fight PEP 668 on a distro Python.

uv tool and pipx installs are detected and reported. They are never started or modified: those environments have no pip for extras, and they usually live under a home directory the service user cannot use. Remove a stale tool install yourself (uv tool uninstall headroom-ai or pipx uninstall headroom-ai) after the managed venv works.

Build the venv from Token Saver when the dashboard offers that repair. For a manual repair, run these commands as the DurinDoor service user with the real DATA_DIR:

python3 -m venv "$DATA_DIR/headroom/venv"
"$DATA_DIR/headroom/venv/bin/python" -m pip install --upgrade 'headroom-ai[proxy,code,ml]'

On Windows the interpreter is Scripts\python.exe under that venv.

Repair setup failures

When setup cannot continue, Token Saver names a code and a repair. Common codes:

A user-scoped install on PATH is reported and not used.

Use the dashboard controls to start, stop, and install extras. Remote status and statistics calls require management credentials, even when dashboard login is disabled. An external proxy is not managed by these start/stop controls.

Auto-configure: if a saved loopback URL is unreachable, it recovers to http://localhost:8787. After start it polls /health. If the new process never answers, auto-configure stops only that process and writes no enable/URL changes. A proxy that was already running is left alone.

Verify compression and recovery

1. Set DATA_DIR to the actual absolute data path and confirm the service user can write it. Confirm a system Python 3.10+ (python3 --version).
2. On Token Saver → Settings, start Headroom (or run the venv commands above).
3. Wait until status says the proxy is reachable, then enable headroomEnabled.
4. Send a large chat request. Statistics show a Headroom token delta only when the proxy accepts a useful reduction. Small or ineligible payloads can stay unchanged.
5. Stop the proxy and send again. The request still completes. Logs show a Headroom skip, not a client error.

If the dashboard says Python is missing while python3 works in your shell, the service user cannot see that interpreter. Install a system Python the DurinDoor process can execute, then retry setup.