OpenCode + DeepSeek

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

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 and generate an API key.

Store it somewhere safe:

export DEEPSEEK_API_KEY="sk-your-deepseek-key-here"

3. Start the proxy

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:

curl http://127.0.0.1:8787/health
# → "status": "healthy"

To see which models the proxy exposes:

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:

HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \
headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1

Verbosity levels:

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:

{
  "$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

Both models support thinking mode for step-by-step reasoning (see below).

Switch models at any time with /model in OpenCode.

5. Start OpenCode

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

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.

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

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:

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)