DOCS · GUIDES
Bring your own model
Three ways to give specd a model — your Claude subscription, an API key, or neither — and what each one costs you in capability.
On this page
specd does not resell inference. You supply the model, and the wizard preflights which of the three modes this machine can actually do.
1 · Your Claude subscription — no API key
specd drives the Claude Code CLI that is already signed in on the machine.
export SPECD_AI_MODE=subscription_runner- Runs consume your subscription quota, so they record tokens but are not metered in euros.
- The reply has no schema guarantee, so it is shape-checked with one repair attempt before giving up — rather than being trusted and failing later.
- Pairs naturally with self-hosted runners: the runner is the machine that is signed in.
2 · An API key
Works from anywhere, is schema-enforced, and is metered per token from a rate card.
export ANTHROPIC_API_KEY=sk-ant-...Money is integer EUR cents throughout — floats never touch it. Spend caps are checked before a run starts, not after it has already cost something. See Costs and metering.
3 · Neither
specd still runs end to end. What you lose is precisely the drafting, and nothing else:
| Works without a model | Needs a model |
|---|---|
| Indexing, retrieval, the document graph | Drafting a spec |
| Knowledge health, coupling, freshness | The judgement half of grounding |
| The scanned half of grounding — commands, CI, services, configuration, entities, test layout | The build station |
The CLI, MCP, verify_citation, the gate | — |
Embeddings are a separate choice
The default embedder is a deterministic local hash: no second API key, works offline. The README-level truth about it is that it is lexical — the full-text arm of retrieval carries relevance until you point the index at a real model. Two ways to do that:
# hosted
SPECD_EMBEDDING_PROVIDER=voyage VOYAGE_API_KEY=...
# any OpenAI-compatible /v1/embeddings endpoint — Ollama, LM Studio,
# llama.cpp, vLLM
SPECD_EMBEDDING_PROVIDER=openai SPECD_EMBEDDING_BASE_URL=http://localhost:11434/v1The second option is the interesting one: the retrieval ceiling comes off without a cloud key and without a repository's knowledge leaving the machine.
Checking what this machine can do
specd doctor # or --json, for CIIt reports config, server, database, embeddings, AI credential, identity and default project in dependency order, and skips what an earlier failure makes unknowable. Optional configuration is a note, never a fault: no platform key, no default project and the built-in embedder are all supported ways to run specd. Exit 4 means something needs fixing.