headroom
squeezes large tool output, such as json, before the model reads it.
- status
- optional ships with colonizer, off until you switch it on.
- version
- bundle 0.37.0-1
- pinned
- bundle 0.37.0-1, headroom-ai 0.37.0 · archive sha256 2aa548fb (x86_64) / 47ad96db (aarch64)
- licence
- apache-2.0
- docs
- token savings
what it does for you
headroom is a proxy inside the colony that compacts large tool results, such as json, before the model reads them. in its smoke test a 400-row json log arrives 75% smaller, every error row kept.
what it needs
- the claude code settler
- a one-time download of 220–245 mb, and about 300–370 mb of the colony’s memory
how to turn it on
settings → modules on the claude code settler: the headroom switch. off by default; switching it on starts the download.
how far it has been tested
it has run in a microvm set up like a colony and reached anthropic through the credential swap. no full claude code session has run through it, and it has not run in a colony yet.
how colonizer runs it
- pinned per architecture in crates/colonizer/headroom.lock (bundle 0.37.0-1, headroom-ai 0.37.0); the pins are compiled into the mothership and nothing is downloaded at install
- the runner starts the proxy on colony loopback and points ANTHROPIC_BASE_URL at it; it forwards to the model router when the colony has provider routes and to anthropic when it does not, so routing, the claude fallback and the credential swap stay where they were
- fixed flags: --no-cache (its semantic cache must never answer for the agent), --stateless, no network of its own, no ml compression, and no credential beyond PATH, LANG and the certificate-bundle variables
- the bundle is a standalone cpython 3.13 with headroom-ai[proxy], built inside debian bookworm and smoke-tested; saving the agent module with headroom on starts the download (POST /api/headroom/download), checked against the compiled pin and unpacked to <data>/headroom/<release>. a colony that starts first runs without it
- if it exits, or is not healthy within 90 seconds, the colony runs without it and its log says why
what it costs
221 mb for aarch64 and 243 mb for x86_64, downloaded once per release; 300 to 370 mb of the colony's memory (measured on arm64); 2.5 to 7 seconds to start.