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

​
Set it up

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

You can only use a BYOK provider that has a stored key; otherwise the CLI tells you to set it first.

​
Pick a model

If you don’t set a model, the provider’s default is used.

​
Check status

buildwithtrace doctor also reports your active model provider.

​
Remove a key

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

​
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.