Skip to main content
By default Trace uses hosted models — no setup beyond authentication, and usage counts against your Trace plan. BYOK lets you point the AI at your own provider key instead. You pay the provider directly, and those requests don’t consume your Trace quota.
Desktop app support is coming. BYOK is fully available in the CLI today. Desktop app integration (configure your key from the chat panel settings) is in active development and will be available in an upcoming release. The same providers, same pipeline, same tool execution — just configured from the desktop UI instead of the terminal.
BYOK still goes through the Trace backend. Your key travels with the request; the backend routes the model call to your provider using Trace’s EDA prompts, tool schemas, and pipeline. You get the same agentic behavior and the same local tool execution — just billed to your provider.

​
Supported providers

Provider valueKeys it reads (env)Example model IDs
anthropicANTHROPIC_API_KEYclaude-sonnet-4-20250514
openaiOPENAI_API_KEYgpt-4o
geminiGEMINI_API_KEY, GOOGLE_API_KEYgemini-2.5-pro
trace—Trace-hosted default (billed to your plan)

​
Set it up

# Store your key (prompts securely; nothing is echoed) and switch to it
buildwithtrace byok set anthropic

# Or pass it explicitly (e.g. in a provisioning script)
buildwithtrace byok set openai --key sk-...
set stores the key in your OS keychain (falling back to a 0600 file) and sets that provider as active. The key is never written to the plaintext config.toml.

​
Switch providers

buildwithtrace byok use openai      # switch active provider
buildwithtrace byok use trace       # back to Trace-hosted models (the default)
You can only use a BYOK provider that has a stored key; otherwise the CLI tells you to set it first.

​
Pick a model

buildwithtrace byok model claude-sonnet-4-20250514
buildwithtrace byok model gpt-4o
If you don’t set a model, the provider’s default is used.

​
Check status

buildwithtrace byok status

Active provider: anthropic
Key configured. Model: claude-sonnet-4-20250514
Billed directly to your provider; does not use Trace quota.
buildwithtrace doctor also reports your active model provider.

​
Remove a key

buildwithtrace byok clear anthropic
If the cleared provider was active, the CLI reverts to Trace-hosted models.

​
Resolution order

For any AI request, the CLI resolves the key in this order:
  1. Environment variable (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY)
  2. Keychain (or the 0600 fallback file)
This makes CI ergonomic — set the provider once and inject the key via an environment secret: 
buildwithtrace byok use anthropic
export ANTHROPIC_API_KEY=sk-ant-...
buildwithtrace agent "Run a DFM pass and fix clearance violations" -p ./board/
If a provider is selected but no key is found, the CLI falls back to Trace-hosted models rather than failing — so a missing CI secret degrades gracefully instead of breaking your pipeline.

​
SDK BYOK (Python & Node)

The SDKs resolve BYOK the same way, so “set once” works from code or CI. Precedence:
  1. Per-call args — chat(..., llm_provider=, llm_api_key=, llm_model_id=) (Python) / chat(msg, { llmProvider, llmApiKey, llmModelId }) (Node)
  2. Environment — TRACE_LLM_PROVIDER, TRACE_LLM_API_KEY, TRACE_LLM_MODEL
  3. Persisted store — the Python SDK also reads the keychain byok set config; the Node SDK additionally accepts constructor defaults (new Trace({ llmProvider, llmApiKey, llmModelId }))
Provider + key are resolved as a unit from the first source that supplies both (a per-call provider is never mixed with an env key). If nothing resolves, the call uses Trace-hosted models. 
export TRACE_LLM_PROVIDER=anthropic
export TRACE_LLM_API_KEY=sk-ant-...
export TRACE_LLM_MODEL=claude-sonnet-4-20250514   # optional

​
Billing implications

  • Trace-hosted (trace) — counts against your Trace monthly budget / credits. Check with buildwithtrace billing status.
  • BYOK (anthropic/openai/gemini) — billed by your provider on your own account. Trace quota is untouched.
BYOK skips Trace’s cost cap, but not the plan gate. You still need at least the plan that unlocks the mode you’re using: agent and plan require a trial or paid plan, even with your own key. ask is free. A free account running agent/plan with BYOK is still rejected (the CLI prints an upgrade CTA and exits 4).
Either way, you still need a valid Trace login (buildwithtrace auth login) — BYOK changes which model answers, not whether you’re authenticated to Trace.

​
Desktop App (Coming Soon)

The desktop app will support BYOK directly from the chat panel settings — no CLI required. The experience will be:
  1. Open Settings → AI Provider in the chat panel
  2. Select your provider (Anthropic, OpenAI, Gemini)
  3. Enter your API key (stored securely in your OS keychain)
  4. Optionally set a specific model ID
The desktop BYOK uses the same backend pipeline as the CLI: your key travels with the request, the backend routes to your provider using Trace’s EDA prompts and tool schemas, and tool execution still happens locally on your files. The only difference is where you configure it.
Desktop BYOK is in active development. Follow the changelog for release announcements.