Transparent credential pass-through; no Headroom auth layer
Date: 2026-06-23 Status: Accepted Decision: hl-poj0 Deciders: Sean Brandt
Context
Section titled “Context”Headroom sits in the LLM request path between clients and upstreams (Anthropic for the agents instance, llm-gw for the apps instance). A decision was required on whether to add an independent authentication gate at the Headroom layer or rely on upstream credential validation plus the network perimeter.
Decision
Section titled “Decision”Headroom forwards Authorization headers to upstreams unchanged and adds no authentication layer of its own. The network boundary (ClusterIP for headroom-apps, Tailscale-only internal DNS for headroom-agents) plus upstream credential validation is the access gate.
Rationale
Section titled “Rationale”- Headroom’s upstream-forwarding model is the documented supported pattern; holding credentials would require cluster-side secret management for Anthropic subscription tokens.
headroom-appsis ClusterIP-only — unreachable from outside the cluster — making an edge auth layer redundant for in-cluster clients.headroom-agentsis bounded by Tailscale membership (an existing auth boundary, single-user homelab); a request still needs a valid Anthropic credential to obtain a completion.- Existing per-app virtual-key budget enforcement at llm-gw is preserved because vkeys pass through intact.
Alternatives Considered
Section titled “Alternatives Considered”- Transparent pass-through, no Headroom auth (chosen): zero new secrets held at Headroom; per-app vkey budget enforcement falls through to llm-gw unchanged; the Anthropic subscription token is never stored in-cluster; posture mirrors llm-gw (internal-only DNS, not public).
- Add a Headroom-level auth gate, e.g. Cloudflare Access or an agentgateway front-door (rejected, deferred): an explicit identity check before forwarding, but added complexity for limited benefit given apps are ClusterIP-internal and agents are Tailscale-bounded and require a valid upstream credential anyway. Retained as a future option if the threat model expands.
Consequences
Section titled “Consequences”- Positive: no cluster-held Anthropic credential (reduced secret surface); per-app budget enforcement at llm-gw is undisturbed; posture is consistent with llm-gw (internal-only, upstream-validated).
- Negative:
headroom-agentshas no Headroom-level identity gate — a Tailscale peer could consume its budget (but cannot obtain completions without a valid Anthropic credential). - Neutral: Cloudflare Access or an agentgateway front-door is explicitly deferred and noted as a future option if the threat model expands.