clawdie-ai/doc/PI-DEEPSEEK-LINUX-SMOKE.md

Pi DeepSeek Linux Smoke

Date: 14.maj.2026
Status: PLANNED — Linux-side provider lane for Colibri validation

Purpose

Validate DeepSeek as the next Pi provider lane on Linux before wiring broader Colibri control flows. This is a provider smoke test, not a FreeBSD host-safety change.

Credential File

Pi stores persistent provider credentials at:

~/.pi/agent/auth.json

DeepSeek is a built-in Pi provider. No custom models.json base URL is needed.

Expected shape:

{
  "deepseek": { "type": "api_key", "key": "<YOUR_DEEPSEEK_KEY>" }
}

Important details:

• field name is key, not apiKey
• type literal is exactly api_key
• do not commit this file
• do not send the key through chat or agent prompts

Alternative: Pi also reads DEEPSEEK_API_KEY, but credential resolution prefers auth.json over environment variables when both exist.

Observed resolution order:

--api-key flag -> auth.json -> OAuth -> env var -> models.json

Local-Only Key Write Pattern

Use a local shell prompt so the key does not pass through an agent transcript. In Pi interactive mode, prefix with ! so it runs locally:

read -rs K

printf '{\n  "deepseek": { "type": "api_key", "key": "%s" }\n}\n' "$K" > ~/.pi/agent/auth.json

unset K

Smoke Test

First list models and record the exact model IDs. Do not hardcode model names before this succeeds.

pi --provider deepseek --list-models

Then run a JSON-mode connectivity smoke test:

pi --provider deepseek -p --mode json "reply with the single word: ok"

Expected result:

• command exits successfully
• output is JSONL
• Colibri can parse the stream with src/colibri-pi-events.ts
• a text delta or final assistant message contains ok

Linux Install Notes

Observed on Linux with user-managed Node (nvm):

• npm i -g @earendil-works/pi-coding-agent succeeds without sudo
• install created ~/.pi/agent/ and auth.json automatically
• no pi init was required
• --mode json, --mode rpc, and -p/--print are available
• default provider is Google if no provider is specified
• DeepSeek and ZAI are first-class providers in Pi

Cross-platform install tooling must detect prefix writability instead of assuming sudo or assuming a user-writable npm prefix.

Colibri Gate

This smoke test supports the Colibri proof gates:

Pi on Linux works
Pi JSON event stream is available
DeepSeek provider lane works through Pi, not through a separate CLI

Non-Goals

• Do not store or handle DeepSeek keys in Clawdie-AI source.
• Do not add DeepSeek-specific CLI support outside Pi.
• Do not hardcode DeepSeek model IDs before --list-models confirms them.
• Do not make this Linux provider smoke test a dependency of FreeBSD host safety.

Related Documents

• doc/COLIBRI-PI-CONTROL-PLAN.md
• doc/INTERAGENT-RUN-CONTRACT.md