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

> Dynamically disable headroom.js compression by sending the x-headroom-mode passthrough header. Bypass compression and route traffic directly to your LLM provider with this complete guide.

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

---

**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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py) to determine whether to bypass compression.

In [`headroom/proxy/helpers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py), the proxy inspects incoming request headers for the `x-headroom-mode` directive:

```python

# 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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts), this automatically adds the `x-headroom-mode` header to all requests:

```typescript
// 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:

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

```bash
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`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/adapters/vercel-ai.ts):

```typescript
// 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:

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