Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs: add guide for using Headroom with OpenCode + DeepSeek (#2497)

suvenkatesh97565c6076efcc
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 6a45b0b4c..554918cc6 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -40,6 +40,7 @@
"vscode-claude-code",
"vscode-copilot",
"opencode",
+ "opencode-deepseek",
"grok-build",
"mcp",
"---Configuration---",
diff --git a/docs/content/docs/opencode-deepseek.mdx b/docs/content/docs/opencode-deepseek.mdx
new file mode 100644
index 000000000..83c21a982
--- /dev/null
+++ b/docs/content/docs/opencode-deepseek.mdx
@@ -0,0 +1,233 @@
+---
+title: OpenCode + DeepSeek
+description: Configure OpenCode to route DeepSeek traffic through the Headroom proxy for compression, output shaping, and savings visibility.
+---
+
+Save 20-60% on DeepSeek API costs with Headroom's context compression proxy.
+
+## How it works
+
+```
+OpenCode → Headroom Proxy (:8787) → DeepSeek API
+ ↑ compresses input
+ + shapes output
+```
+
+The proxy sits between OpenCode and DeepSeek. It compresses tool outputs, logs,
+and search results before they reach the model, then shapes responses to be
+concise. DeepSeek's API is OpenAI-compatible — one flag and you're running.
+
+---
+
+## 1. Install Headroom
+
+```bash
+pip install headroom-ai
+# or via uv:
+uv tool install headroom-ai
+```
+
+You get SmartCrusher (structural compression), the proxy, output shaping, and
+the MCP server — everything you need.
+
+---
+
+## 2. Get your DeepSeek API key
+
+Sign up at [platform.deepseek.com](https://platform.deepseek.com) and generate
+an API key.
+
+Store it somewhere safe:
+```bash
+export DEEPSEEK_API_KEY="sk-your-deepseek-key-here"
+```
+
+---
+
+## 3. Start the proxy
+
+```bash
+headroom proxy \
+ --port 8787 \
+ --openai-api-url https://api.deepseek.com/v1
+```
+
+The proxy auto-detects `api.deepseek.com` and labels itself "DeepSeek" on the
+dashboard. Verify it's running:
+
+```bash
+curl http://127.0.0.1:8787/health
+# → "status": "healthy"
+```
+
+To see which models the proxy exposes:
+```bash
+curl -s http://127.0.0.1:8787/v1/models \
+ -H "Authorization: Bearer sk-your-key" | jq '.data[].id'
+```
+
+### With output shaping (optional)
+
+Output shaping makes the model's responses shorter — fewer tokens, lower cost:
+
+```bash
+HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \
+headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1
+```
+
+Verbosity levels:
+
+| Level | Behavior |
+|---|---|
+| `1` | Skip preambles/postambles |
+| `2` | + Don't restate code/file content already in context (**recommended**) |
+| `3` | + Omit rationale unless asked |
+| `4` | Maximum — fragments, zero fluff |
+
+---
+
+## 4. Configure OpenCode
+
+**Note:** If you have an existing `~/.config/opencode/opencode.json` (for MCP
+servers, etc.), merge the provider section into that file. Having both `.json`
+and `.jsonc` in the same directory can cause conflicts.
+
+Edit `~/.config/opencode/opencode.json`:
+
+```jsonc
+{
+ "$schema": "https://opencode.ai/config.json",
+ "model": "headroom/deepseek-v4-pro",
+ "provider": {
+ "headroom": {
+ "npm": "@ai-sdk/openai-compatible",
+ "name": "Headroom Proxy",
+ "options": {
+ "baseURL": "http://127.0.0.1:8787/v1",
+ "apiKey": "sk-your-deepseek-key"
+ },
+ "models": {
+ "deepseek-v4-pro": {
+ "name": "DeepSeek V4 Pro",
+ "limit": { "context": 1000000, "output": 384000 }
+ },
+ "deepseek-v4-flash": {
+ "name": "DeepSeek V4 Flash",
+ "limit": { "context": 1000000, "output": 384000 }
+ }
+ }
+ }
+ },
+ "mcp": {
+ "headroom": {
+ "type": "local",
+ "command": ["headroom", "mcp", "serve"],
+ "enabled": true
+ }
+ }
+}
+```
+
+**Important:** Only include model IDs that appear in the proxy's `/v1/models`
+response. OpenCode validates config models against the proxy's model list.
+The current DeepSeek model names are `deepseek-v4-pro` and `deepseek-v4-flash`.
+`deepseek-chat` and `deepseek-reasoner` are deprecated compatibility aliases.
+
+### Model comparison
+
+| Model | Input / Output (per 1M) | Context | Max Output |
+|---|---|---|---|
+| `deepseek-v4-pro` | $0.435 / $0.87 | 1M | 384K |
+| `deepseek-v4-flash` | $0.14 / $0.28 | 1M | 384K |
+
+Both models support **thinking mode** for step-by-step reasoning (see below).
+
+Switch models at any time with `/model` in OpenCode.
+
+---
+
+## 5. Start OpenCode
+
+```bash
+opencode
+```
+
+Run `/models` to confirm both DeepSeek models appear under "Headroom Proxy".
+Select one with `/model deepseek-v4-flash` or `/model deepseek-v4-pro`.
+
+---
+
+## 6. Check savings
+
+```bash
+curl http://127.0.0.1:8787/stats | python3 -m json.tool | grep -A5 compression
+```
+
+Or open the dashboard at [http://127.0.0.1:8787/dashboard](http://127.0.0.1:8787/dashboard).
+
+---
+
+## Thinking mode (reasoning)
+
+Both models support thinking mode natively, and DeepSeek enables it by default.
+This replaces the deprecated `deepseek-reasoner` (R1) model.
+See [DeepSeek's thinking mode docs](https://api-docs.deepseek.com/guides/thinking_mode)
+for details on switching between thinking and non-thinking modes.
+
+---
+
+## Common issues
+
+### "Authentication Fails" / Unauthorized
+
+The `apiKey` in OpenCode's config is missing or wrong. OpenCode must send the
+API key to the proxy, and the proxy forwards it to DeepSeek. Make sure
+`"apiKey": "sk-..."` is set under `options`.
+
+### Models don't appear under "Headroom Proxy"
+
+1. Verify the proxy is running: `curl http://127.0.0.1:8787/health`
+2. Check which models the proxy exposes: `curl -s http://127.0.0.1:8787/v1/models -H "Authorization: Bearer sk-your-key"`
+3. Make sure your config model IDs match **exactly** what the proxy returns
+4. Don't use both `opencode.json` and `opencode.jsonc` in the same config directory — use one file
+
+### Models appear but requests fail
+
+You ran `headroom wrap opencode`. That command replaces your config with Claude
+and GPT models. **Do not use `headroom wrap`.** Configure OpenCode manually as
+shown above, and launch OpenCode directly with `opencode`.
+
+### "headroom" command not found
+
+`uv tool install` puts binaries in `~/.local/bin/`. Add it to your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Output shaping shows no savings
+
+Output savings are measured against a learned baseline (it compares "what the
+model actually emitted" vs "what it would have emitted unshaped"). After a few
+sessions, run:
+
+```bash
+headroom learn --verbosity --apply
+```
+
+This builds the baseline, and `/stats` will show output savings numbers. The
+shaper is active immediately — the numbers just need calibration.
+
+---
+
+## What's NOT in this guide
+
+- **Claude or GPT models** — this setup uses DeepSeek exclusively
+- **`headroom wrap`** — do not use it; it overrides the config
+- **Deprecated model names** — `deepseek-chat` and `deepseek-reasoner` are
+ compatibility aliases that will be deprecated on 2026-07-24; use
+ `deepseek-v4-pro` and `deepseek-v4-flash` instead
+- **Kompress (ML compression)** — requires extra dependencies; SmartCrusher
+ handles the majority of use cases
+- **Any code changes** — headroom ships full DeepSeek support natively
+ (model tables, pricing, tokenizers, domain detection)