--- title: "Deploy Headroom" description: "Headroom compression proxy. Cuts LLM token usage" category: "AI/ML" url: https://railway.com/deploy/headroom --- # Deploy Headroom Headroom compression proxy. Cuts LLM token usage **[Deploy Headroom on Railway](https://railway.com/template/headroom)** - **Creator:** darseen - **Category:** AI/ML - **Total deploys:** 5 ## Template content ### Headroom https://vaze.up.railway.app/api/hosting/headroom.png - **Image:** ghcr.io/chopratejas/headroom:0.6.7-code-nonroot - **Health check:** /readyz - **Public domain:** Yes ## Documentation # Deploy and Host Headroom on Railway Headroom is a context-compression proxy for AI agents and apps. It sits between your agent and an LLM provider and shrinks request context before forwarding it upstream — cutting token usage (up to 60–95% on JSON-heavy payloads, ~15–20% on coding-agent traffic) while preserving answer quality. Point any OpenAI- or Anthropic-compatible client at it with a one-line base-URL change. ## About Hosting Headroom This template runs a single public service from the published image `ghcr.io/chopratejas/headroom`. Your client sends requests to the service's URL instead of the provider directly; Headroom compresses each request and forwards it to Anthropic (`/v1/messages`) or OpenAI (`/v1/chat/completions`, `/v1/responses`). It is a **bring-your-own-key relay** — it stores no provider keys and forwards the `x-api-key` / `Authorization` your client sends. A volume at `/home/nonroot/.headroom` persists config, the compression-model cache, and savings history. **First boot is slow**: the image loads a ModernBERT compression model before `/readyz` reports healthy, so initial deploys take a few minutes — the healthcheck window is set to 600 s to allow for this. ## Common Use Cases - **Shrink coding-agent context** — put Headroom in front of Claude Code, Codex, or Copilot to trim tool output and large files out of every request. - **Cut cost on JSON/RAG pipelines** — compress bulky JSON context before it reaches the model without changing your application code. - **A shared team compression endpoint** — one hosted proxy your whole team (or your other Railway services) routes LLM traffic through. ## Dependencies for Headroom Hosting - **An upstream LLM provider key** — supplied by the *caller* per request (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI). The proxy stores none, so you do not configure a provider key on the service itself. - **A persistent volume** — mounted at `/home/nonroot/.headroom` for the workspace, model cache, and savings history (provisioned automatically by this template). ### Deployment Dependencies - Upstream project: - Container image: [`ghcr.io/chopratejas/headroom`](https://github.com/headroomlabs-ai/headroom/pkgs/container/headroom) (tag `0.6.7-code-nonroot` — code-aware compression, non-root) - Compression model: `kompress-v2-base` (ModernBERT), loaded at startup. ### Implementation Details **Single public service + volume.** The `proxy` service is the only one with a public domain (port **8787**, healthcheck `/readyz`). A volume mounted at `/home/nonroot/.headroom` persists the workspace across deploys. **Port pinning.** Both `HEADROOM_PORT` and Railway's canonical `PORT` are set to `8787`. Railway's deploy healthcheck probes `PORT`; if it does not match the port the app binds, the deploy never becomes healthy. This is the single most important variable to keep aligned if you change the port. **Security model.** `HEADROOM_PROXY_TOKEN` is a generated secret, but Headroom exempts loopback callers and Railway's public edge is seen as loopback — so the token does **not** authenticate public-URL traffic (it does gate non-loopback callers such as other services on Railway's private network). Your real protection is that the proxy is a bring-your-own-key relay: callers must supply valid upstream credentials to get a response. See [VARIABLES.md](./VARIABLES.md) for the full explanation. **Why not Qdrant + Neo4j?** Headroom's upstream `docker-compose.yml` bundles them for its optional memory feature, but memory is off by default, its default backend is local SQLite (needs only the volume), and the `qdrant-neo4j` backend hardcodes `neo4j://localhost:7687` with no override — so a separate Neo4j service cannot be wired in. They are intentionally omitted. Point your client's base URL at the service's public URL: ```bash # Claude Code / Anthropic ANTHROPIC_BASE_URL=https://.up.railway.app claude # Codex / OpenAI-compatible OPENAI_BASE_URL=https://.up.railway.app/v1 your-app ``` ## Why Deploy Headroom on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Headroom on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ## Similar templates - [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform. - [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage. - [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack Open this page in a browser: https://railway.com/deploy/headroom