Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
services:
cli:
image: ${HEADROOM_IMAGE:-ghcr.io/headroomlabs-ai/headroom:latest}
entrypoint: ["headroom"]
working_dir: /workspace
stdin_open: true
tty: true
environment:
HOME: /tmp/headroom-home
# Docker creates /tmp/headroom-home as root:root, so $HOME is not
# writable by the --user the container runs as (issue #4207). Keep the
# HuggingFace/XDG caches on the bind-mounted workspace instead.
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
# Canonical Headroom filesystem contract (issue #175). Forwarded into
# the container so the proxy resolves state/config to the bind-mounted
# /tmp/headroom-home/.headroom path. HEADROOM_WORKSPACE (above) remains
# the Docker bind-mount source and is intentionally different.
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
volumes:
- ${HEADROOM_WORKSPACE:-.}:/workspace
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
command: ["--help"]
proxy:
image: ${HEADROOM_IMAGE:-ghcr.io/headroomlabs-ai/headroom:latest}
entrypoint: ["headroom", "proxy"]
working_dir: /workspace
restart: unless-stopped
environment:
HOME: /tmp/headroom-home
# See the `cli` service above (issue #4207).
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
HEADROOM_HOST: 0.0.0.0
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
# The container binds 0.0.0.0 so the loopback publication below can reach
# it; the proxy refuses that bind without a token unless the operator
# acknowledges it. This file always publishes on 127.0.0.1, so it does.
# Irrelevant (and harmless) once HEADROOM_PROXY_TOKEN is set.
HEADROOM_ALLOW_UNAUTHENTICATED_BIND: "1"
# Canonical Headroom filesystem contract (issue #175). See `cli` service
# above for rationale.
HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroom
HEADROOM_CONFIG_DIR: /tmp/headroom-home/.headroom/config
ports:
- "127.0.0.1:${HEADROOM_PORT:-8787}:${HEADROOM_PORT:-8787}"
volumes:
- ${HEADROOM_WORKSPACE:-.}:/workspace
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.headroom:/tmp/headroom-home/.headroom
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.claude:/tmp/headroom-home/.claude
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.codex:/tmp/headroom-home/.codex
- ${HEADROOM_HOST_HOME:?set HEADROOM_HOST_HOME}/.gemini:/tmp/headroom-home/.gemini
command: ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]