mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-10 14:27:00 -04:00
8cc5354f51
## Description Install commands across the docs referenced the unpublished `headroom` package instead of the published `headroom-ai`, so copy-pasted `pip install` commands fail. This corrects them to `headroom-ai` (with extras). Closes #1014 ## Type of Change - [x] Documentation update ## Changes Made - `wiki/getting-started.md`: corrected 4 `pip install headroom` commands to `headroom-ai` (including the `[proxy]`, `[relevance]`, and `[all]` extras). - `docs/content/docs/claude-code-vertex.mdx`: fixed the install command on line 37. - `SECURITY.md`: fixed the install command on line 47. ## Testing - [x] Manual verification ### Test Output ```text $ rg -n "pip install headroom\b" docs wiki SECURITY.md (no matches — all bare `headroom` install commands now use `headroom-ai`) ``` ## Real Behavior Proof - Environment: Windows 11, repo working tree on branch fix/docs-1014-headroom-ai-pkg - Exact command / steps: Grepped the docs tree for `pip install headroom` before and after the edits. - Observed result: Before, several occurrences referenced the unpublished `headroom`; after, only `headroom-ai` remains (the spec doc reference is intentionally left untouched). - Not tested: Did not run a live `pip install headroom-ai` against PyPI in CI. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
140 lines
2.9 KiB
Markdown
140 lines
2.9 KiB
Markdown
# Getting Started with Headroom
|
|
|
|
This guide will help you get up and running with Headroom in under 5 minutes.
|
|
|
|
## Installation
|
|
|
|
**Python:**
|
|
|
|
```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/chopratejas/headroom/main/scripts/install.sh | bash
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
irm https://raw.githubusercontent.com/chopratejas/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_applied}")
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Proxy Server Documentation](proxy.md) - Configure the proxy
|
|
- [Transforms Reference](transforms.md) - Understand each transform
|
|
- [API Reference](api.md) - Full API documentation
|