Skip to content

headroom-apps is retired — in-cluster apps call the LiteLLM Service directly; headroom-agents stays for the laptop Claude Code path

Date: 2026-09-23 Status: Accepted — supersedes hl-g0fn Deciders: Sean Brandt

ADR hl-g0fn split Headroom into two instances by run mode. headroom-agents runs in cache mode for Claude Code on the operator laptop. headroom-apps ran in token mode in front of LiteLLM for octopus, karakeep and mealie. The apps set OPENAI_BASE_URL to headroom-apps, which compressed the request and forwarded it to https://llm.fzymgc.house/v1.

LiteLLM has a headroom guardrail that calls /v1/compress on a Headroom instance before the model call. The plan was to move the apps to that guardrail and attach it to their virtual keys. Two measurements on 2026-09-23 showed that neither path saved much for these apps:

  1. The LiteLLM_SpendLogs rows for the previous seven days show the request shape. octopus made 42 completion requests with 1.7 messages on average and about 11k characters each. karakeep made 8 and mealie made 7, each one message of about 63 characters. No request carried a tool result.
  2. The LiteLLM hook (guardrail_hooks/headroom in v1.103.0-rc.1) never sends system messages, the last user message or assistant messages to Headroom. It compresses only earlier user turns and tool results. Through the live guardrail, a single-turn request saved 0 tokens and a request with an earlier tool result saved 21%.

As a middlebox, headroom-apps compressed only the octopus user messages, a few hundred thousand characters a week. The guardrail would compress none of the apps’ traffic.

Remove headroom-apps. octopus, karakeep and mealie call the LiteLLM Service at http://litellm.litellm.svc.cluster.local:4000/v1. The litellm-proxy-ingress CiliumNetworkPolicy admits each app pod on 4000. The headroom-compression guardrail, the headroom-apps Uptime Kuma monitor and the Velero exclusion go with it.

headroom-agents stays unchanged. It serves the laptop Claude Code subscription path to api.anthropic.com in cache mode, off LiteLLM.

The apps use the Service and not https://llm.fzymgc.house. Cilium WireGuard encrypts pod-to-pod traffic, and each workload key carries allowed_routes = ["llm_api_routes"], so the route through Traefik added a hop and a certificate dependency with no security gain. The policy admits only the workload pods, not their namespaces, because a direct caller can reach the unauthenticated UI and DCR routes that the IngressRoute hides.

  • The apps lose the compression of octopus user messages. At the measured volume, this costs cents a week.
  • One fewer service, namespace, PVC and monitor to run.
  • The LiteLLM guardrail is no longer defined. If a workload with long multi-turn or tool-heavy context appears, measure its request shape in LiteLLM_SpendLogs first. fovea is the only current key with that shape (4.3 messages per request, 94% of its characters outside the last user message).
  • To roll back, revert the removal PR and the repoint PR (#2253). ArgoCD recreates the instance with an empty savings ledger.