How to Dynamically Enable or Disable headroom.js Compression

TLDR: Send the x-headroom-mode: passthrough header (case-insensitive) with your request to instantly bypass headroom.js compression, or configure headroomMode: "passthrough" in the TypeScript or Python SDK clients to disable it dynamically.

The Headroom proxy (chopratejas/headroom) accelerates LLM API calls through intelligent compression via its headroom.js pipeline. While compression is enabled by default to reduce bandwidth costs, the proxy provides built-in mechanisms to dynamically disable it per-request using specific HTTP headers recognized by the request handlers.

How the Bypass Mechanism Works

The proxy evaluates incoming requests for bypass directives before applying any compression transforms. This logic resides in specific helper modules that set a passthrough flag determining whether to skip the compression pipeline entirely.

Header Detection in helpers.py

In headroom/proxy/helpers.py, the system inspects request headers for the bypass directive using a case-insensitive check:

# headroom/proxy/helpers.py

passthrough = str(headers.get("x-headroom-mode", "")).strip().lower() == "passthrough"

This code normalizes the header value to lowercase and compares it against the string "passthrough", ensuring that Passthrough or PASSTHROUGH work equally well.

Compression Decision Logic

The boolean flag propagates to headroom/proxy/compression_decision.py, where it short-circuits the compression workflow:

# headroom/proxy/compression_decision.py

if passthrough:
    # bypass all compression steps

When passthrough evaluates to True, the proxy routes the request directly to the downstream LLM provider without applying headroom.js transforms.

Methods to Dynamically Disable headroom.js

You can disable compression through multiple interfaces depending on your integration method.

Using the x-headroom-mode Header

The most direct method involves adding the x-headroom-mode header to your HTTP requests:

curl -X POST https://api.your-llm.com/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "x-headroom-mode: passthrough" \
     -d '{"model":"gpt-4","messages":[...]}'

This approach works with any HTTP client and requires no SDK installation, making it ideal for testing and debugging scenarios.

TypeScript SDK Configuration

When using the official TypeScript SDK (sdk/typescript/src/client.ts), set the headroomMode option:

// sdk/typescript/src/client.ts
import { HeadroomClient } from "headroom-ai";

const client = new HeadroomClient({
  baseUrl: "http://localhost:8787",
  headroomMode: "passthrough"   // disables compression for this client
});

The SDK automatically translates this option into the required HTTP header for all outgoing requests.

Python SDK Implementation

For Python applications, pass the header through the client constructor:

from headroom import HeadroomClient

client = HeadroomClient(
    base_url="http://localhost:8787",
    headers={"x-headroom-mode": "passthrough"}   # disable

)

Legacy x-headroom-bypass Support

The proxy also recognizes the legacy x-headroom-bypass header in headroom/proxy/helpers.py for backward compatibility. Setting this header to any truthy value (e.g., "true") triggers the same passthrough behavior:

x-headroom-bypass: true

While functional, x-headroom-mode is the preferred modern approach as documented in the current source code.

Practical Implementation Examples

When integrating with framework-specific middleware, the bypass header can be injected automatically.

Vercel AI SDK Middleware (sdk/typescript/src/adapters/vercel-ai.ts):

import { headroomMiddleware } from "headroom-ai/vercel-ai";

const middleware = [
  headroomMiddleware({ headroomMode: "passthrough" }), // disable compression
  otherMiddleware(),
];

Python Raw Request:

import requests

response = requests.post(
    "http://localhost:8787/v1/chat/completions",
    headers={"x-headroom-mode": "passthrough"},
    json={"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}
)

Summary

• Primary disable method: Send x-headroom-mode: passthrough header (case-insensitive) to dynamically bypass compression
• Legacy support: Use x-headroom-bypass: true for backward compatibility with older implementations
• SDK integration: TypeScript SDK uses headroomMode: "passthrough"; Python SDK passes headers directly
• Source implementation: Header detection lives in headroom/proxy/helpers.py; bypass execution occurs in headroom/proxy/compression_decision.py
• Dynamic scope: Disabling compression is per-request and requires no proxy restarts or persistent configuration changes

Frequently Asked Questions

What is the difference between x-headroom-mode and x-headroom-bypass?

The x-headroom-mode header accepts specific operational modes like "passthrough" and represents the current standard implemented in headroom/proxy/helpers.py. The x-headroom-bypass header is a legacy Boolean flag maintained for backward compatibility that triggers the same passthrough effect when set to any truthy value.

Can I re-enable headroom.js compression after disabling it?

Yes. Since the bypass mechanism operates on a per-request basis via headers, simply omitting the x-headroom-mode or x-headroom-bypass headers from subsequent requests automatically restores normal compression behavior. There is no persistent state change or global configuration modification when using these headers.

Does disabling compression affect the response format?

No. When you set x-headroom-mode: passthrough, the proxy acts as a transparent passthrough as implemented in headroom/proxy/compression_decision.py. The response format from the downstream LLM provider remains identical to a direct API call, simply without the compression transforms that headroom.js normally applies to request and response bodies.

Is the passthrough header case-sensitive?

No. As explicitly implemented in headroom/proxy/helpers.py, the header value conversion uses .lower() for case-insensitive comparison. Therefore, Passthrough, PASSTHROUGH, and passthrough are all valid values that will successfully disable headroom.js compression for that request.

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