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 (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 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:

# 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.