# Headroom Environment Variables: Complete Configuration Guide

> Master Headroom environment variables for complete configuration control. Explore live-runtime knobs, proxy-wide settings, and observability features in our comprehensive guide.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: configuration-guide
- Published: 2026-06-20

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```bash
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:

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

```

Export OpenTelemetry metrics to Prometheus:

```bash
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:

```bash
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/runtime_env.py), while proxy-wide settings are documented in [`wiki/proxy.md`](https://github.com/chopratejas/headroom/blob/main/wiki/proxy.md) and filesystem-related variables in [`wiki/filesystem-contract.md`](https://github.com/chopratejas/headroom/blob/main/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.