# Headroom.js Configuration Options: Complete Guide to the CompressOptions Interface

> Explore headroom.js configuration with the CompressOptions interface. Learn to control model selection, proxy endpoints, authentication, timeouts, retries, and compression for optimal performance.

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

---

**Headroom.js accepts a `CompressOptions` object that controls model selection, proxy endpoints, authentication, timeouts, retries, and compression behavior.**

The Headroom SDK (maintained in the `chopratejas/headroom` repository) configures its behavior through the `CompressOptions` interface defined in [`sdk/typescript/src/types.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/types.ts). These configuration options govern how the JavaScript SDK communicates with the Headroom proxy, manage compression budgets, and handle network resilience when compressing LLM messages.

## Endpoint and Authentication Settings

Configure where the SDK sends requests and how it authenticates using these **core connection options**.

- **`baseUrl`** – A `string` specifying the base URL of the Headroom proxy. If omitted, the SDK defaults to `http://localhost:8787`.
- **`apiKey`** – A `string` containing the API key for proxy authentication, passed via the `X‑Headroom‑Api‑Key` header.
- **`stack`** – A `string` identifier sent via the `X‑Headroom‑Stack` header (for example, `"adapter_js_openai"`), used for observability and routing.

## Model Selection and Token Budgets

Control which LLM the proxy invokes and how aggressively the SDK compresses content.

- **`model`** – A `string` identifying the LLM model (such as `"gpt-4"`) that the proxy should use when generating text.
- **`tokenBudget`** – A `number` specifying the desired maximum token count for the compressed output. The SDK compresses until this budget is met.

## Reliability and Resilience Options

Fine-tune how the SDK handles network failures and unavailable proxies.

- **`timeout`** – A `number` defining the request timeout in milliseconds.
- **`retries`** – A `number` setting the count of automatic retries for failed proxy requests.
- **`fallback`** – A `boolean` that, when set to `true`, enables the SDK to fall back to a local compression routine when the proxy is unreachable.

## Advanced Extensibility

Integrate custom logic and monitoring through these **extension options**.

- **`client`** – An optional `HeadroomClientInterface` implementation that replaces the default HTTP client. This is useful for testing or advanced integrations requiring custom transport layers.
- **`hooks`** – A `CompressionHooks` object supplying `preCompress` and `postCompress` callbacks for custom processing of messages before and after compression.

## Configuration Examples

### Basic Usage with Default Settings

```typescript
import { compress } from "headroom-ai";

const result = await compress([
  { role: "user", content: "Explain quantum computing in simple terms." }
]);

console.log(result.messages);

```

### Custom Model and Proxy URL

```typescript
import { compress } from "headroom-ai";

const result = await compress(
  [{ role: "user", content: "Summarize the latest AI research papers." }],
  {
    model: "gpt-4",
    baseUrl: "https://my-headroom-proxy.example.com",
    apiKey: "my-secret-key",
    tokenBudget: 500,      // keep the response under 500 tokens
  }
);

console.log(`Tokens before: ${result.tokensBefore}`);
console.log(`Tokens after: ${result.tokensAfter}`);

```

### Using Compression Hooks for Custom Preprocessing

```typescript
import { compress, type CompressionHooks } from "headroom-ai";

const myHooks: CompressionHooks = {
  preCompress: async (messages) => {
    // Add a system prompt before compression
    return [{ role: "system", content: "You are a helpful assistant." }, ...messages];
  },
  postCompress: async (compressed) => {
    // Log the transforms applied by the proxy
    console.log("Transforms:", compressed.transformsApplied);
    return compressed;
  },
};

await compress(
  [{ role: "user", content: "How does blockchain work?" }],
  { hooks: myHooks, stack: "my_custom_integration" }
);

```

### Fallback to Local Compression When the Proxy Is Down

```typescript
import { compress } from "headroom-ai";

await compress(
  [{ role: "user", content: "Give me a short story about a dragon." }],
  { fallback: true, retries: 2, timeout: 3000 }
);

```

## Summary

- The **`CompressOptions`** interface in [`sdk/typescript/src/types.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/types.ts) defines all available configuration options for headroom.js.
- **Connection settings** include `baseUrl` (defaulting to `http://localhost:8787`), `apiKey`, and `stack` for proxy communication.
- **Compression control** is managed via `model` and `tokenBudget` to limit output size and specify which LLM the proxy should invoke.
- **Resilience options** (`timeout`, `retries`, `fallback`) ensure the SDK handles network failures gracefully by retrying requests or falling back to local compression.
- **Extension points** (`hooks` and `client`) allow custom preprocessing, postprocessing, and complete HTTP client replacement as implemented in [`sdk/typescript/src/client.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts).

## Frequently Asked Questions

### What is the default proxy URL for headroom.js?

If you do not specify a `baseUrl` in the configuration options, the SDK defaults to `http://localhost:8787`. This assumes you are running a Headroom proxy locally on the default port.

### How do I authenticate with a Headroom proxy?

Pass your API key via the `apiKey` option in the `CompressOptions` object. The SDK sends this value as the `X‑Headroom‑Api‑Key` header with every request to the proxy endpoint.

### What happens when the proxy is unreachable?

When you set `fallback: true` in the configuration, the SDK attempts local compression if the proxy returns an error or times out. You can also configure `retries` and `timeout` values to control retry behavior before the fallback activates.

### How do I customize the compression behavior with hooks?

Supply a `hooks` object containing `preCompress` and/or `postCompress` functions. The `preCompress` hook receives messages before they are sent to the proxy, allowing you to inject system prompts or modify content. The `postCompress` hook receives the compressed result, enabling logging or additional transformation before the SDK returns the final output.