Configuration

Headroom can be configured via the SDK constructor, proxy command line, environment variables, or per-request overrides.

Runtime Rollout ChannelsCopy Anchor Link

Headroom uses rollout channels to control which behaviors an already-installed artifact may expose. They do not select a package or released version.

See Runtime Rollouts for policy, provenance, and contributor rules. If Codex history disappeared after using an older wrapper, see Recover Codex State before wrapping Codex again.

SDK Modes (default_mode / headroom_mode)Copy Anchor Link

These modes apply to SDK usage via HeadroomClient(default_mode=...) or per-request headroom_mode=.... They are not the same as the proxy --mode flag.

Proxy --mode is a separate axis: --mode cache (the default) freezes prior turns so the provider's prefix cache is never busted, which is where the savings come from on a real agent workload. --mode token maximizes visible per-request compression at the cost of cache stability; prefer cache unless you are specifically diagnosing compression numbers. The proxy does not accept audit, optimize, or simulate.

SDK ConfigurationCopy Anchor Link

import { HeadroomClient } from 'headroom-ai';

// Reads from HEADROOM_BASE_URL and HEADROOM_API_KEY automatically
const client = new HeadroomClient();

// Or configure explicitly
const explicit = new HeadroomClient({
  baseUrl: 'http://localhost:8787',
  apiKey: 'your-api-key',
  timeout: 30_000,
  fallback: true,
  retries: 2,
});

Per-Request OverridesCopy Anchor Link

Override configuration for individual requests:

import { compress } from 'headroom-ai';

const result = await compress(messages, {
  model: 'gpt-4o',
  tokenBudget: 100_000,
  timeout: 15_000,
});

Proxy upstream override (x-headroom-base-url)Copy Anchor Link

When using the proxy, send the x-headroom-base-url request header to route a single request to a different upstream instead of the configured provider URL. This lets a client that speaks a provider's wire format authenticate against a compatible gateway (for example an OpenAI-compatible endpoint, or an Anthropic-Messages gateway such as OpenCode Zen) without changing the proxy configuration.

The header is honored by the OpenAI-compatible routes, the Anthropic Messages route (POST /v1/messages), and the generic passthrough route. The proxy forwards the request to <x-headroom-base-url> + the original request path (e.g. /v1/messages). An empty or whitespace-only value is ignored and the configured upstream is used.

curl http://127.0.0.1:8787/v1/messages \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-headroom-base-url: https://opencode.ai/zen/go" \
  -H "x-api-key: <gateway-api-key>" \
  -d '{"model":"glm-5.2","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

When HEADROOM_STRIP_INTERNAL_HEADERS is enabled (the default), the proxy reads this header for routing and then strips it before forwarding upstream.

Configured secret headers are not sent to arbitrary upstreamsCopy Anchor Link

ANTHROPIC_TARGET_API_HEADERS / OPENAI_TARGET_API_HEADERS hold operator secrets. Because x-headroom-base-url is chosen by the client, those headers are only attached when the destination is one the operator designated:

• a host in the configured provider targets (ANTHROPIC_TARGET_API_URL, OPENAI_TARGET_API_URL, and the Gemini/Vertex/Cloud Code equivalents), or
• a host listed in HEADROOM_UPSTREAM_ALLOWED_HOSTS (comma-separated).

A request to any other upstream is still proxied — it just does not carry your configured headers, and the proxy logs upstream_extra_headers_withheld host=<host> once per host. If you route to a gateway via this header and need your configured headers to reach it, add its host to HEADROOM_UPSTREAM_ALLOWED_HOSTS:

export HEADROOM_UPSTREAM_ALLOWED_HOSTS="gateway.internal,api.example-gateway.ai"

Matching is on the parsed hostname and is exact — no wildcards — so api.anthropic.com.evil.example and https://api.anthropic.com@evil.example do not match api.anthropic.com.

x-headroom-base-url is refused when an outbound proxy is in the wayCopy Anchor Link

Because the destination is chosen by the client, the proxy validates it by resolving the hostname and rejecting non-public addresses — and then dials the address it validated, rather than resolving the name a second time at connect time. Without that second half, a hostname whose authoritative DNS is attacker-controlled can answer the check with a public address and the connection with 169.254.169.254 or an RFC1918 host (DNS rebinding).

An outbound HTTP or SOCKS proxy (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) is handed the target by name — in the request line, in CONNECT, in the SOCKS5 address — and resolves it itself, from its own network, after the check ran. Headroom cannot enforce the validated address there, so a request carrying x-headroom-base-url that would route through the proxy is refused rather than forwarded on a verdict nothing enforces.

This affects only client-supplied upstreams. Every operator-configured provider URL goes through the proxy exactly as before. If you need a specific endpoint reachable via x-headroom-base-url through an outbound proxy, name it in HEADROOM_ALLOWED_BASE_URLS — an explicit operator decision to admit that destination by name, which also turns off the resolve-and-pin check for it.

SmartCrusher ConfigurationCopy Anchor Link

Fine-tune JSON compression behavior:

from headroom.transforms import SmartCrusherConfig

config = SmartCrusherConfig(
    # Maximum items to keep after compression
    max_items_after_crush=15,

    # Minimum tokens before applying compression
    min_tokens_to_crush=200,

    # Fraction of items always kept from the start/end
    first_fraction=0.3,
    last_fraction=0.15,

    # Variance threshold for statistical analysis
    variance_threshold=2.0,
)

CacheAligner ConfigurationCopy Anchor Link

Control prefix stabilization for provider cache hit rates:

from headroom import CacheAlignerConfig

config = CacheAlignerConfig(
    # Enable/disable cache alignment
    enabled=True,

    # Use custom regex patterns instead of the built-in dynamic-content
    # detector (use_dynamic_detector=False activates date_patterns)
    use_dynamic_detector=False,
    date_patterns=[
        r"Today is \w+ \d+, \d{4}",
        r"Current time: .*",
    ],
)

Context Window ManagementCopy Anchor Link

Context management is now automatic. Use per-request overrides to control behavior:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    # Reserve tokens for model output
    headroom_output_buffer_tokens=4000,
    # Keep last N turns uncompressed
    headroom_keep_turns=3,
)

The RollingWindowConfig, IntelligentContextConfig, and ScoringWeights classes are no longer part of Headroom. Context management now happens automatically inside the pipeline (live-zone-only compression).

Claude 1M context window (headroom wrap claude --1m)Copy Anchor Link

headroom wrap claude --1m opts a Claude Code session into Anthropic's 1M-token context window by selecting a [1m]-suffixed model id, which makes Claude Code send the context-1m beta header. The model that --1m targets is resolved in this order:

1. an explicit --model / ANTHROPIC_MODEL value (used as-is, with a [1m] suffix appended when missing),
2. otherwise HEADROOM_1M_MODEL, when set,
3. otherwise the built-in default (currently claude-opus-5).

Set HEADROOM_1M_MODEL to point --1m at a specific model without pinning ANTHROPIC_MODEL globally, so the default can follow a new Opus generation without a code change:

# Route --1m at a specific model for this shell / session
export HEADROOM_1M_MODEL=claude-opus-5
headroom wrap claude --1m

HEADROOM_1M_MODEL is a fallback only: an explicit --model or ANTHROPIC_MODEL always wins. The value may be given with or without the [1m] suffix; both claude-opus-5 and claude-opus-5[1m] are accepted, and the suffix is added when absent.

For Claude Code's official VS Code extension, use the client-owned persisted setting instead of ANTHROPIC_MODEL:

headroom wrap vscode-claude --1m

This writes the resolved model with exactly one [1m] suffix to the top-level model setting in Claude Code's user settings and records the prior presence and value in Headroom's reversible sidecar. Running the command without --1m restores a model previously managed by Headroom; headroom unwrap vscode-claude restores the model and proxy environment values together. Use --no-configure --1m to print the setting without writing either file.

Claude Code and Anthropic own model support and account eligibility. Local tests prove settings persistence and restoration, not a live entitled VS Code session or a resulting 1M context window.

Pipeline ExtensionsCopy Anchor Link

Use a headroom.pipeline_extension entry point when you need to normalize or annotate requests before they leave Headroom. The PRE_SEND stage is the right place for provider-specific request cleanup, such as turning content: null into content: "" for upstreams that reject OpenAI-spec tool-call messages.

from headroom.pipeline import PipelineEvent, PipelineStage


class NormalizeNullContent:
    def on_pipeline_event(self, event: PipelineEvent) -> PipelineEvent:
        if event.stage is not PipelineStage.PRE_SEND or not event.messages:
            return event

        for message in event.messages:
            if (
                message.get("role") == "assistant"
                and message.get("content") is None
                and message.get("tool_calls")
            ):
                message["content"] = ""

        return event

Register it in pyproject.toml:

[project.entry-points."headroom.pipeline_extension"]
normalize_null_content = "my_pkg.normalize:NormalizeNullContent"

If the upstream base URL itself must vary per request, use the x-headroom-base-url override header in addition to the normalization hook.

Proxy ConfigurationCopy Anchor Link

Command Line OptionsCopy Anchor Link

headroom proxy \
  --port 8787 \              # Port to listen on
  --host 127.0.0.1 \         # Host to bind to
  --mode cache \             # default; freezes prior turns for prefix-cache stability
  --budget 10.00 \           # Daily budget limit in USD
  --log-file headroom.jsonl  # Log file path

Feature FlagsCopy Anchor Link

# Disable optimization (passthrough mode)
headroom proxy --no-optimize

# Disable semantic caching
headroom proxy --no-cache

# Preserve provider prefix-cache stability instead of maximizing token removal
headroom proxy --mode cache

# Enable memory and live learning
headroom proxy --memory
headroom proxy --learn --min-evidence 3

Environment VariablesCopy Anchor Link

For provider-only proxying, prefer HEADROOM_HTTP_PROXY over process-wide variables such as HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, or NO_PROXY. HTTPX reads those global variables, but Headroom also passes them through to tool executions.

Cold-prefix hook & reasoning compactionCopy Anchor Link

Two related optimizations target tokens that agent harnesses re-send every turn: model reasoning (re-billed as input on Kimi/GLM/DeepSeek and on Claude 4.6+), and the prefix itself once its prompt cache has lapsed. All flags below are off by default — the base proxy is unchanged until you opt in.

What to set for what:

How cold detection knows the TTL. A wrong "cold" call would recompact a warm prefix and bust the cache, so the TTL must be right:

• Claude Code: read exactly, from the request's cache_control.ttl plus CC's own controls — ENABLE_PROMPT_CACHING_1H (1h), FORCE_PROMPT_CACHING_5M (5m), and DISABLE_PROMPT_CACHING (+ per-model DISABLE_PROMPT_CACHING_<FAMILY>), which turns caching off and makes every turn a free recompaction candidate.
• Kimi / OpenAI / Codex: they don't expose a TTL, so detection uses a conservative default until the learner (HEADROOM_CACHE_TTL_LEARN + the headroom-cache-ttl plugin) fills in the real value from observed hits/misses.

Running the estimator. With HEADROOM_CACHE_TTL_LEARN=1 set on the proxy, run the batch estimator periodically (cron / launchd — it is deliberately out-of-process so it can never touch the request path):

headroom-cache-ttl            # reads cache_ttl_observations.jsonl, writes cache_ttl_learned.json
headroom-cache-ttl --dry-run  # print the estimate table without writing

It emits a TTL for a provider/model only when the observations bound it on both sides — hits at some idle prove the cache was still alive (lower bound), ttl_expiry misses at a larger idle prove it was dead (upper bound) — and it writes the upper end of that interval: overestimating a TTL only skips a recompaction, while underestimating one would bust a warm cache. Estimates are never pooled across models: one model's expiry says nothing about another's TTL, so a cross-model aggregate could close one model's interval with another's death evidence. Keys without death-evidence beyond their last observed hit are skipped, as is any model with no estimate of its own; both keep the conservative static default. The proxy picks up a rewritten table by mtime; no restart needed.

Can these be on by default?

• HEADROOM_THINKING_COMPACT — stays opt-in. It rewrites model inputs (reasoning the model actively uses) and depends on Kompress, so its quality / latency trade should be a deliberate choice.
• HEADROOM_COLD_RECOMPACT — opt-in today; a candidate to default for Claude Code once TTL detection is field-validated. It only fires on confirmed-cold turns and recompacts losslessly, but a mis-read TTL would bust a warm cache (expensive), so it waits for confidence. For Kimi/OpenAI it should stay opt-in until the learner has data.
• HEADROOM_CACHE_TTL_LEARN — the safest to default on: observation-only, a size-bounded local log, and it respects HEADROOM_STATELESS. Kept opt-in for now so nothing is written to disk unasked.

Cost-aware model routingCopy Anchor Link

Complementary to content compression, Headroom can rewrite the upstream model per request to stretch quota and control spend, for example by sending small, tool-free requests to a cheaper model. Routing is opt-in and disabled by default, so behavior is unchanged unless you configure it.

Enable it with HEADROOM_MODEL_ROUTER_ENABLED=1 and declare ordered rules in HEADROOM_MODEL_ROUTES (a JSON array). The router evaluates rules top to bottom and the first rule whose conditions all match wins; every decision is logged with a reason so routing stays observable. Each rule object supports:

export HEADROOM_MODEL_ROUTER_ENABLED=1
export HEADROOM_MODEL_ROUTES='[
  {"name": "small-no-tools", "max_input_tokens": 4000, "require_no_tools": true,
   "from_models": ["claude-sonnet-4-6"], "to_model": "claude-haiku-4-5"}
]'

Notes:

• Combine max_input_tokens with max_output_tokens to downshift only turns that are cheap on both sides: a tiny prompt that asks for a long answer (a large max_tokens) stays on the original model.
• Input size is a fast, tokenizer-free estimate over the messages, tools, and top-level system prompt, meant for tier selection rather than exact accounting.
• A malformed rule fails open: it is skipped (never silently widened), and the rest of the rules still apply.
• Routing is skipped for byte-faithful passthrough requests (x-headroom-bypass: true or x-headroom-mode: passthrough), so those are never model-rewritten.
• Routing currently applies on the Anthropic /v1/messages path.

Session Beta Header TrackingCopy Anchor Link

When running as a proxy, Headroom maintains a per-session union of anthropic-beta (and OpenAI-Beta) tokens via SessionBetaTracker. The session key is derived from the x-headroom-session-id header if present, otherwise from md5(model + system_prompt[:500])[:16] — stable across turns of the same conversation.

Why: clients such as Claude Code and Codex CLI may drop a beta token between consecutive turns. Because anthropic-beta is part of the request bytes that determine the upstream prefix-cache key, a dropped token would bust the cache mid-conversation. The tracker re-injects any token seen earlier in the session so the cache key stays stable.

Trade-off: once the proxy has seen a beta token in a session it will continue re-sending it for the rest of that session, even if the client stops including it. Stopping the token on the client side alone is not sufficient — the proxy re-injects it. Set HEADROOM_BETA_HEADER_STICKY=disabled to pass the client's anthropic-beta value verbatim and bypass this accumulation.

# Disable sticky beta re-echo
export HEADROOM_BETA_HEADER_STICKY=disabled
headroom proxy ...

Note: disabling sticky mode may reduce prefix-cache hit rates for clients that legitimately drop-and-re-add beta tokens across turns.

Filesystem ContractCopy Anchor Link

Headroom resolves every on-disk resource through a two-root model (HEADROOM_CONFIG_DIR + HEADROOM_WORKSPACE_DIR) with additive precedence rules: explicit argument > per-resource env var > derived from canonical root > default. Every legacy env var continues to work unchanged.

See the Filesystem Contract page for the full bucket table, plugin-author guidance, and the Docker naming overlap note (HEADROOM_WORKSPACE is not the same as HEADROOM_WORKSPACE_DIR).

Custom Model ConfigurationCopy Anchor Link

Configure context limits and pricing for new or custom models:

{
  "anthropic": {
    "context_limits": {
      "claude-4-opus-20250301": 200000,
      "claude-custom-finetune": 128000
    },
    "pricing": {
      "claude-4-opus-20250301": {
        "input": 15.00,
        "output": 75.00,
        "cached_input": 1.50
      }
    }
  },
  "openai": {
    "context_limits": {
      "ft:gpt-4o:my-org": 128000,
      "my-private-deployment": 200000
    },
    "pricing": {
      "my-private-deployment": [5.00, 15.00]
    }
  }
}

Save as ${HEADROOM_CONFIG_DIR}/models.json (defaults to ~/.headroom/config/models.json), or set HEADROOM_MODEL_LIMITS to a JSON string or file path. Installs that still have ~/.headroom/models.json (the legacy location) continue to work.

Where limits and prices come fromCopy Anchor Link

Headroom consults the installed LiteLLM model database (litellm.model_cost) for public model metadata. That data ships with the LiteLLM package rather than being fetched at runtime, so it is as current as your installed LiteLLM version and refreshes when you upgrade it. Nothing here makes a network call.

Limits and prices do not use the same precedence. Both are first-match-wins:

Context limits

1. Explicit configuration and the built-in table, checked together — they are merged into one mapping, so an exact match in either returns immediately, then partial/prefix matches.
2. LiteLLM (max_input_tokens) — reached only for models the previous step didn't match.
3. Pattern inference, then a generic default.

Pricing

1. Explicit configuration — a value you configured is a decision, so it beats everything below.
2. LiteLLM.
3. Built-in table, then pattern inference, then a generic default.

Limits are an input budget (max_input_tokens), not the total window: gpt-5 resolves to 272K input, not the 400K total (272K in + 128K out).

LiteLLM also resolves gateway-routed names — azure/..., bedrock/..., vertex_ai/..., groq/... — which the built-in tables never covered.

The built-in tables additionally cover installs where LiteLLM is unavailable: the dependency is gated python_version < '3.14'.

Pattern-Based InferenceCopy Anchor Link

Models that reach step 3 and match no table entry are inferred from naming patterns:

Matching prefers the most specific prefix, so gpt-4.1 is not treated as gpt-4 (which would give it an 8K limit and legacy gpt-4 pricing).

Provider-Specific SettingsCopy Anchor Link

Provider classes configure token counting and context/pricing overrides, not cache toggles -- provider-specific cache optimization (Anthropic cache_control breakpoints, OpenAI prefix stabilization, Google CachedContent) is controlled by enable_cache_optimizer on HeadroomClient (see SDK Configuration above), which auto-detects the right strategy from the provider you pass in.

from headroom import OpenAIProvider

provider = OpenAIProvider(
    context_limits={"gpt-4o": 128000},
)

Tool ProfilesCopy Anchor Link

Skip or customize compression for specific tools:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    headroom_tool_profiles={
        "important_tool": {"skip_compression": True},
        "search_tool": {"max_items_after_crush": 25},
    },
)

Configuration PrecedenceCopy Anchor Link

Settings are applied in this order (later overrides earlier):

1. Default values
2. Environment variables
3. SDK constructor arguments
4. Per-request overrides

ValidationCopy Anchor Link

Validate your configuration at startup:

result = client.validate_setup()

if not result["valid"]:
    print("Configuration issues:")
    for check in ("provider", "storage", "config", "cache_optimizer"):
        if result[check]["error"]:
            print(f"  - {check}: {result[check]['error']}")