How to Disable headroom.js Dynamically: A Complete Guide to Bypassing Compression

Send the x-headroom-mode: passthrough header (or x-headroom-bypass: true) with your request to dynamically disable headroom.js compression and route traffic directly to the downstream LLM provider.

The chopratejas/headroom repository provides a proxy service that uses headroom.js to compress LLM API requests. When you need to disable headroom.js dynamically for specific requests without redeploying client code, you can use special HTTP headers that trigger a passthrough mode, bypassing all compression logic on the server.

How the Bypass Mechanism Works

The headroom proxy checks for special headers in headroom/proxy/helpers.py to determine whether to bypass compression.

In headroom/proxy/helpers.py, the proxy inspects incoming request headers for the x-headroom-mode directive:

# headroom/proxy/helpers.py

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

When this header is present, a boolean passthrough flag is set to true. This flag propagates to the compression decision logic in headroom/proxy/compression_decision.py, where it causes the proxy to skip all compression steps and treat the request as already uncompressed.

Methods to Disable headroom.js Dynamically

Using the x-headroom-mode Header

The primary method to disable headroom.js dynamically is sending the x-headroom-mode: passthrough header with your HTTP request. The header check is case-insensitive, so Passthrough or PASSTHROUGH also work.

Using the Legacy x-headroom-bypass Header

The proxy also supports the legacy header x-headroom-bypass. Setting this header to any truthy value (such as "true") triggers the same passthrough behavior as the primary header.

Using the TypeScript SDK

When using the TypeScript SDK, set the headroomMode option to "passthrough" in the client configuration. As implemented in sdk/typescript/src/client.ts, this automatically adds the x-headroom-mode header to all requests:

// 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
});

Using the Python SDK

For Python applications, pass the header directly through the client options:

from headroom import HeadroomClient

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

)

Practical Code Examples

cURL Request

Disable compression for a single API call using cURL:

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":[{"role":"user","content":"Hello"}]}'

Node.js with Middleware

When composing middleware with the Vercel AI SDK, disable headroom.js as follows according to sdk/typescript/src/adapters/vercel-ai.ts:

// sdk/typescript/src/adapters/vercel-ai.ts
import { headroomMiddleware } from "headroom-ai/vercel-ai";

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

Python SDK Initialization

Initialize the Python client with passthrough mode enabled:

from headroom import HeadroomClient

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

Summary

• Use the x-headroom-mode: passthrough header to disable headroom.js dynamically on a per-request basis according to the source code in headroom/proxy/helpers.py.
• Alternative legacy header x-headroom-bypass: true provides the same functionality for backward compatibility.
• SDK integration is available via the headroomMode option in TypeScript or by passing headers in the Python SDK.
• No code redeployment required when using raw HTTP headers, making this ideal for testing and debugging compression behavior.

Frequently Asked Questions

Is the x-headroom-mode header case-sensitive?

No, the header value is normalized using .strip().lower() in headroom/proxy/helpers.py, so Passthrough, PASSTHROUGH, and passthrough are all valid.

Can I disable headroom.js globally instead of per-request?

The header-based bypass mechanism in headroom/proxy/helpers.py is designed for per-request control. Global configuration would require modifying the proxy configuration or environment variables, which is not covered in the current header-based bypass implementation.

Does the passthrough mode affect response compression?

When passthrough is set to true in headroom/proxy/compression_decision.py, the proxy skips all compression steps for that request. This typically means responses are also returned without compression, though the exact behavior depends on downstream provider configuration.

What happens if I send both x-headroom-mode and x-headroom-bypass headers?

The proxy checks for both headers in headroom/proxy/helpers.py. If either header triggers the passthrough condition (either x-headroom-mode: passthrough or x-headroom-bypass with a truthy value), the compression bypass is activated.

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