# How to Dynamically Enable or Disable headroom.js Compression

> Dynamically enable or disable headroom.js compression by sending the x-headroom-mode passthrough header or configuring the SDK client. Bypass compression instantly.

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

---

**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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py), the system inspects request headers for the bypass directive using a case-insensitive check:

```python

# 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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/compression_decision.py), where it short-circuits the compression workflow:

```python

# 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:

```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":[...]}'

```

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`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts)), set the `headroomMode` option:

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

```

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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py) for backward compatibility. Setting this header to any truthy value (e.g., `"true"`) triggers the same passthrough behavior:

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

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

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

```

**Python Raw Request**:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/helpers.py); bypass execution occurs in [`headroom/proxy/compression_decision.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.