mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
`wiki/` **is not published anywhere.** `.github/workflows/docs.yml` says so in its own header, no mkdocs or sphinx config exists, and `wiki/**` sits in `paths-ignore` for CI — changes there don't even run a build. It survives as pending-migration reference material for contributors. That's why this is separate from the published-site work in #3388: nothing here reaches a user through `docs.headroomlabs.ai`. It still matters, because a contributor migrating a page would carry its errors across, and because the repo is public. ## The finding that justifies this PR on its own `wiki/benchmarks.md` carried an entire **invented "Production Telemetry" section**, presented as real-world fleet data: > real-world production telemetry from 250+ active proxy instances … **52ms median overhead** … **1.4 billion tokens saved** across 249 instances Plus P90/P99 timings, ~$4,000 saved, an OS split, a version-share breakdown, and a dated collection window of March 30 – April 2, 2026. A repo-wide grep for those figures **matches only that one file.** No script, test or fixture produces them. The published benchmarks page never carried the section, so the site owner had already excised it. Removed rather than re-estimated. The per-category ranges hanging off it (4.8%, 40–80%, 83–94%, 85–94%, 60–76%) went with it and now point at the concrete compression table on the same page. The same page also described `HEADROOM_TELEMETRY` as the opt-in switch governing fleet-wide numbers. Fleet data would come from `HEADROOM_BEACON` — a **separate switch that defaults ON**. That note is gone with the section it footnoted; the accurate description of both switches shipped to the live site in #3388. ## Other corrections, each verified against source - **`wiki/agno.md`** constructed `HeadroomAgnoModel(config=...)`; the field is `headroom_config` (`integrations/agno/model.py:135`). The sibling `HeadroomPreHook` genuinely does take `config`, which is how they got conflated. - **`wiki/ccr.md`** documented CLI flags that don't exist, and a dead demo script. - **`wiki/image-compression.md`** had two broken CLI examples. - **`wiki/getting-started.md`** used `plan.transforms_applied`; `SimulationResult` exposes `transforms`. (`CompressResult` really does have `transforms_applied` — two different result types, easy to cross.) - **`wiki/cli.md`** documents 15 of ~27 top-level commands; an audit note now says so rather than implying completeness. ## Disposition, for whoever picks up the migration `wiki/cli.md` is the highest-value page to port — no site page is a full CLI reference, and `docs.yml` names it as the reason `wiki/` still exists. `wiki/integration-guide.md` and `wiki/configuration.md` also cover ground the site doesn't. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
151 lines
3.1 KiB
Markdown
151 lines
3.1 KiB
Markdown
# Getting Started with Headroom
|
|
|
|
This guide will help you get up and running with Headroom in under 5 minutes.
|
|
|
|
## Installation
|
|
|
|
**CLI on macOS Apple Silicon/Linux with uv:**
|
|
|
|
```bash
|
|
uv tool install --python 3.13 "headroom-ai[all]"
|
|
headroom --version
|
|
```
|
|
|
|
Use `uv tool update-shell` if the install succeeds but `headroom` is not on
|
|
`PATH`.
|
|
|
|
**Python project / virtualenv:**
|
|
|
|
```bash
|
|
# Core package (minimal dependencies)
|
|
pip install headroom-ai
|
|
|
|
# With proxy server
|
|
pip install "headroom-ai[proxy]"
|
|
|
|
# With semantic relevance (for smarter compression)
|
|
pip install "headroom-ai[relevance]"
|
|
|
|
# Everything
|
|
pip install "headroom-ai[all]"
|
|
```
|
|
|
|
**TypeScript / Node.js:**
|
|
|
|
```bash
|
|
npm install headroom-ai
|
|
```
|
|
|
|
**Docker-native:**
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.sh | bash
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
irm https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/scripts/install.ps1 | iex
|
|
```
|
|
|
|
See [Docker-native install](docker-install.md) for wrapper behavior, compose usage, and host-integrated `wrap` flows.
|
|
|
|
If you want Headroom to stay up in the background and automatically serve supported tools, use [Persistent Installs](persistent-installs.md):
|
|
|
|
```bash
|
|
headroom install apply --preset persistent-service --providers auto
|
|
```
|
|
|
|
## Quick Start: Proxy Mode (Recommended)
|
|
|
|
The easiest way to use Headroom is as a proxy server:
|
|
|
|
```bash
|
|
# Start the proxy
|
|
headroom proxy --port 8787
|
|
```
|
|
|
|
Then point your LLM client at it:
|
|
|
|
```bash
|
|
# Claude Code
|
|
ANTHROPIC_BASE_URL=http://localhost:8787 claude
|
|
|
|
# GitHub Copilot CLI (default Anthropic-style proxy route)
|
|
headroom wrap copilot -- --model claude-sonnet-4-20250514
|
|
|
|
# OpenAI-compatible clients
|
|
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
|
|
```
|
|
|
|
That's it! All your requests now go through Headroom and get optimized automatically.
|
|
|
|
## Quick Start: Python SDK
|
|
|
|
If you want programmatic control:
|
|
|
|
```python
|
|
from headroom import HeadroomClient
|
|
from openai import OpenAI
|
|
|
|
# Create a wrapped client
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="optimize",
|
|
)
|
|
|
|
# Use exactly like the original
|
|
response = client.chat.completions.create(
|
|
model="gpt-4o",
|
|
messages=[
|
|
{"role": "system", "content": "You are a helpful assistant."},
|
|
{"role": "user", "content": "Hello!"},
|
|
],
|
|
)
|
|
```
|
|
|
|
## Modes
|
|
|
|
### Audit Mode
|
|
|
|
Observe without modifying:
|
|
|
|
```python
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="audit",
|
|
)
|
|
# Logs metrics but doesn't change requests
|
|
```
|
|
|
|
### Optimize Mode
|
|
|
|
Apply transforms to reduce tokens:
|
|
|
|
```python
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="optimize",
|
|
)
|
|
# Compresses tool outputs, aligns cache prefixes, etc.
|
|
```
|
|
|
|
### Simulate Mode
|
|
|
|
Preview what optimizations would do:
|
|
|
|
```python
|
|
plan = client.chat.completions.simulate(
|
|
model="gpt-4o",
|
|
messages=[...],
|
|
)
|
|
print(f"Would save {plan.tokens_saved} tokens")
|
|
print(f"Transforms: {plan.transforms}")
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Proxy Server Documentation](proxy.md) - Configure the proxy
|
|
- [Transforms Reference](transforms.md) - Understand each transform
|
|
- [API Reference](api.md) - Full API documentation
|