Headroom Compression

What It Does

Headroom is a context-compression service that rewrites bulky tool output and retrieved documents before a request reaches the model. It is generally available on the CBorg API, but it is off by default – you must opt in per request or per model to use it.

Headroom only compresses tool-role message content (the results of tool calls, retrieved documents, and similar bulky machine-generated output). Your own prose – system prompts, user turns, assistant replies – is never rewritten. This means agentic coding workloads that accumulate large tool results benefit the most, with reductions approaching 50% of prompt tokens on tool-heavy traffic. Ordinary conversational chat, which carries little or no tool output, will see little or no change even when enabled.

Warning

Compression is lossy: the model sees a shortened form of the compressed sections, and Headroom’s compressor has been found in some cases to alter tool-call results in ways that are not byte-preserving (for example, stripping tokens from code in a way that changes its meaning). Only enable compression for requests where exact tool output is not required, and verify the results for your own workload before relying on it. If the compression service is unavailable, a request that opted in still proceeds uncompressed rather than failing.

Enabling Compression

Compression is off unless a request explicitly opts in. There are two ways to opt in:

Option 1: Request body

Add a guardrails field naming headroom to the request body:

curl https://api.cborg.lbl.gov/chat/completions \
  -H "Authorization: Bearer $CBORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "guardrails": ["headroom"],
    "messages": [{"role": "user", "content": "Hello"}]
  }'

With the OpenAI Python SDK, pass the same field through extra_body:

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["CBORG_API_KEY"],
    base_url="https://api.cborg.lbl.gov",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"guardrails": ["headroom"]},
)

Option 2: -compact model variant

Every chat model has a matching -compact variant that routes the request through Headroom without needing to modify the request body:

claude-sonnet-5           # normal, no compression
claude-sonnet-5-compact   # same model, compression enabled

This is the only path available to clients that cannot set extra body fields or headers, such as LibreChat.

Disabling Compression Per Request

If compression is enabled (via either method above), it can be turned back off for an individual request by sending the x-headroom-bypass HTTP header with value true:

curl https://api.cborg.lbl.gov/chat/completions \
  -H "Authorization: Bearer $CBORG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-headroom-bypass: true" \
  -d '{
    "model": "claude-sonnet-5-compact",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

This header can be added by any client capable of setting custom HTTP headers on its outgoing requests. When set, the request is forwarded to the model completely unmodified.

See Also