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

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. 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

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

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

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

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 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.

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.

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