Headroom Environment Variables: Complete Configuration Guide

Headroom is controlled almost entirely by environment variables that fall into three categories: live-runtime knobs (hot-reloadable), proxy-wide configuration (read at startup), and observability features.

The chopratejas/headroom repository uses environment variables as its primary configuration mechanism. These Headroom environment variables control everything from output token shaping and verbosity levels to telemetry backends and filesystem paths. Understanding the three distinct categories allows you to tune the proxy behavior without modifying source code.

Live-Runtime Knobs (Hot-Reloadable)

Variables defined in headroom/proxy/runtime_env.py are read on every request and can be updated dynamically via POST /admin/runtime-env without restarting the proxy.

Output Token Shaping with HEADROOM_OUTPUT_SHAPER

The HEADROOM_OUTPUT_SHAPER boolean acts as the master switch for output token shaping (default: off). When enabled, the proxy applies compression strategies to reduce token usage in LLM responses.

Verbosity Control Variables

Control response length using HEADROOM_VERBOSITY_LEVEL (integer 0-4, where unset uses learned defaults) or enable automatic tuning with HEADROOM_VERBOSITY_AUTOTUNE, which activates the AIMD verbosity controller.

Effort Routing Configuration

For mechanical continuations, HEADROOM_EFFORT_ROUTER lowers computational effort, while HEADROOM_MECHANICAL_EFFORT specifies the exact effort value string used for these predictable completions.

A/B Testing and Interception Thresholds

Set HEADROOM_OUTPUT_HOLDOUT to a float between 0 and 1 to reserve that fraction of conversations for A/B measurement. Use HEADROOM_INTERCEPT_READ_MIN_CHARS to configure the minimum character threshold before AST-grep read-rewrite logic activates.

Proxy-Wide Configuration (Startup Variables)

These variables are read once when the proxy starts and are documented in wiki/proxy.md.

Network and Endpoint Settings

Configure the proxy's network presence using HEADROOM_BASE_URL (default http://localhost:8787), HEADROOM_HOST (set to 0.0.0.0 for all interfaces), and HEADROOM_PORT (default 8787).

Authentication and Operation Mode

HEADROOM_API_KEY authenticates requests to Headroom Cloud, while HEADROOM_MODE selects between token (token-reduction) and cache (cache-stable) operation modes. Set HEADROOM_BUDGET to a float like 100.0 to enforce daily USD spend limits.

Code Awareness and Filesystem Paths

Enable AST-based code compression with HEADROOM_CODE_AWARE_ENABLED. Control file locations using HEADROOM_WORKSPACE_DIR (default ~/.headroom), HEADROOM_SAVINGS_PATH, HEADROOM_TOIN_PATH, or HEADROOM_SUBSCRIPTION_STATE_PATH to override default ledger and telemetry locations as defined in wiki/filesystem-contract.md.

Observability and Optional Features

Telemetry and OpenTelemetry Integration

Set HEADROOM_TELEMETRY to on or off to control the anonymous data-flywheel beacon. For OpenTelemetry, set HEADROOM_OTEL_METRICS_ENABLED=1, then configure HEADROOM_OTEL_METRICS_EXPORTER (otlp_http or console), HEADROOM_OTEL_METRICS_ENDPOINT, and HEADROOM_OTEL_SERVICE_NAME (default headroom-proxy).

Enable Langfuse tracing by setting HEADROOM_LANGFUSE_ENABLED=1 (requires additional LANGFUSE_* variables).

Backend and Runtime Selection

Select hardware acceleration using HEADROOM_KOMPRESS_BACKEND (options: cpu, pytorch_mps, onnx_coreml) or HEADROOM_EMBEDDER_RUNTIME. Force specific implementations with HEADROOM_DETECT_BACKEND (python or rust) or adjust tokenizer timeouts with HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS.

Agent Identity and Learning Configuration

Identify the agent type via HEADROOM_AGENT_TYPE (e.g., claude, codex, cursor). Control which CLI to learn from using HEADROOM_LEARN_CLI (claude, gemini, or codex) as documented in wiki/learn.md.

Use HEADROOM_BETA_HEADER_STICKY (set to disabled to pass client headers verbatim) for troubleshooting, and HEADROOM_IN_DOCKER=1 when containerized to adjust path resolution.

Practical Configuration Examples

Enable output shaping dynamically:

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

# Hot-reload without restart:

curl -X POST http://localhost:8787/admin/runtime-env \
     -d '{"HEADROOM_OUTPUT_SHAPER":"1"}'

Configure custom workspace and savings ledger:

export HEADROOM_WORKSPACE_DIR=$HOME/.myheadroom
export HEADROOM_SAVINGS_PATH=$HOME/.myheadroom/custom_savings.json
headroom proxy

Export OpenTelemetry metrics to Prometheus:

export HEADROOM_OTEL_METRICS_ENABLED=1
export HEADROOM_OTEL_METRICS_EXPORTER=otlp_http
export HEADROOM_OTEL_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
headroom proxy

Select Apple Silicon GPU acceleration:

export HEADROOM_KOMPRESS_BACKEND=pytorch_mps
headroom proxy

Summary

• Headroom environment variables are categorized into live-runtime knobs (hot-reloadable), proxy-wide configuration (startup), and observability features.
• Runtime knobs like HEADROOM_OUTPUT_SHAPER and HEADROOM_VERBOSITY_LEVEL are defined in headroom/proxy/runtime_env.py and support dynamic updates via the admin endpoint.
• Startup configuration includes network settings (HEADROOM_HOST, HEADROOM_PORT), authentication (HEADROOM_API_KEY), and filesystem overrides (HEADROOM_WORKSPACE_DIR).
• Observability variables control telemetry, OpenTelemetry metrics, and backend selection for compression and embedding operations.

Frequently Asked Questions

What is the difference between live-runtime knobs and proxy-wide configuration variables?

Live-runtime knobs are read on every request and can be hot-reloaded via POST /admin/runtime-env without restarting the proxy, whereas proxy-wide configuration variables are read once at startup and require a restart to change.

How do I enable output token shaping in Headroom?

Set the environment variable HEADROOM_OUTPUT_SHAPER=1 before starting the proxy, or push the change dynamically using the runtime environment endpoint if the proxy is already running.

Where are Headroom environment variables documented in the source code?

Live-runtime knobs are defined in headroom/proxy/runtime_env.py, while proxy-wide settings are documented in wiki/proxy.md and filesystem-related variables in wiki/filesystem-contract.md.

Can I use environment variables to configure OpenTelemetry metrics in Headroom?

Yes, set HEADROOM_OTEL_METRICS_ENABLED=1 and configure the exporter type, endpoint, and service name using HEADROOM_OTEL_METRICS_EXPORTER, HEADROOM_OTEL_METRICS_ENDPOINT, and HEADROOM_OTEL_SERVICE_NAME respectively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}