> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Key (Desktop)

> Use your own Anthropic, OpenAI, or Gemini API key in the Trace desktop app. Requests are billed to your provider and don't count against your Trace quota.

<Info>
  Desktop BYOK UI is in active development. The backend fully supports BYOK today — the [CLI](/resources/cli-byok) provides complete access. The desktop Settings panel for configuring your key directly from the chat panel is coming in an upcoming release.
</Info>

## What BYOK Does

By default, Trace uses hosted models on AWS Bedrock — no setup needed, and usage counts against your Trace plan. **Bring Your Own Key (BYOK)** lets you point the AI at your own provider key instead:

* **You pay your provider directly** (Anthropic, OpenAI, or Google)
* **Requests don't consume your Trace quota** (monthly budget or On-Demand credits are untouched)
* **Same pipeline** — Trace's EDA prompts, tool schemas, research tools, and local tool execution all work identically
* **Same quality** — the AI reasoning, file editing, and validation workflow is unchanged

BYOK changes *which model answers* your requests. It does not change how Trace works, what tools are available, or how your files are handled.

## Supported Providers

| Provider            | Default Model               | Notes                                       |
| ------------------- | --------------------------- | ------------------------------------------- |
| **Anthropic**       | `claude-sonnet-4-6`         | Same model family as Trace's hosted default |
| **OpenAI**          | `gpt-4o`                    | Chat Completions API                        |
| **Gemini**          | `gemini-2.5-flash`          | Google AI (`google-genai` SDK)              |
| **Trace** (default) | Claude Sonnet 4 via Bedrock | Billed to your Trace plan                   |

You can specify any model your provider supports by setting the model ID explicitly. The defaults above are used when no model is specified.

## How It Works

```mermaid theme={null}
flowchart LR
  Desktop["Desktop App"] -->|"message + your API key"| Backend["Trace Backend"]
  Backend -->|"routes to your provider"| Provider["Anthropic / OpenAI / Gemini"]
  Provider -->|"model response"| Backend
  Backend -->|"SSE stream"| Desktop
  Desktop -->|"tool execution (local)"| Files["Your Files"]
```

1. Your message is sent to the Trace backend along with your provider key
2. The backend routes the model call to your provider using Trace's EDA system prompt, tool schemas, and conversation history
3. Your provider returns the response
4. Tool calls (file reads, writes, DRC, etc.) still execute locally on your machine — identical to Trace-hosted
5. The response streams back to you in real-time

Your API key travels with the request but is never stored on the Trace backend. It's used for that single request and discarded.

## What Still Requires Trace Authentication

BYOK changes the billing target for AI requests, but you still need a Trace account because:

* **Tool execution** requires the desktop app to be authenticated (the backend identifies you via JWT)
* **Conversation history** is stored per-user
* **Mode access gating** still applies — on the Free plan, Agent/Plan modes require [free agent credits](/guides/billing#free-agent-credits) (or a paid plan) even with your own key
* **Research tools** (web search, parts search, datasheet parsing) run on Trace's infrastructure regardless of which model answers

<Note>
  BYOK bypasses the **cost cap** (your provider bills you directly), but it does not bypass **mode access**. Free users with remaining free agent credits *can* use Agent/Plan with BYOK — however, those requests still deplete free agent credits at the token-equivalent rate. Free credits meter your *access* to agentic modes, not Trace's model spend, so they're consumed even though your provider pays for the tokens. Once your free credits are exhausted, Agent/Plan with BYOK requires a paid plan (Pro, Ultra, On-Demand) or an active legacy trial.
</Note>

## Using BYOK Today (via CLI)

Until the desktop Settings UI ships, you can use BYOK through the [Trace CLI](/resources/cli-byok):

```bash theme={null}
# Store your Anthropic key and activate it
buildwithtrace byok set anthropic

# Or OpenAI
buildwithtrace byok set openai --key sk-...

# Switch between providers
buildwithtrace byok use anthropic
buildwithtrace byok use trace       # back to Trace-hosted

# Set a specific model
buildwithtrace byok model claude-sonnet-4-20250514

# Check current status
buildwithtrace byok status
```

Keys are stored in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux libsecret). They are never written to plaintext config files.

For full CLI BYOK documentation, see [CLI BYOK Reference](/resources/cli-byok).

## Billing Implications

| Scenario               | Who pays                                  | Trace quota affected? |
| ---------------------- | ----------------------------------------- | --------------------- |
| Default (Trace-hosted) | Your Trace subscription or credit balance | Yes                   |
| BYOK (your own key)    | Your provider account directly            | No                    |

With BYOK active:

* Your monthly Trace budget is not consumed
* Your On-Demand credits are not deducted
* **Exception:** on the Free plan, [free agent credits](/guides/billing#free-agent-credits) still deplete at the token-equivalent rate for Agent/Plan requests — they gate access to agentic modes, not who pays for tokens
* Usage is still logged for analytics (request counts, timestamps) but no cost is recorded against your Trace profile
* You still appear as an authenticated user in conversation history

## Desktop Settings UI (Coming Soon)

The desktop app will have a dedicated configuration panel:

1. Open **Settings** in the chat panel (gear icon)
2. Navigate to **AI Provider**
3. Select your provider (Anthropic, OpenAI, Gemini, or Trace default)
4. Enter your API key (stored in your OS keychain — same secure storage as your Trace auth token)
5. Optionally specify a model ID
6. Save — all subsequent requests route through your provider

No restart required. The change takes effect on the next message you send.

<Tip>
  Follow the [changelog](/changelog) for the desktop BYOK release announcement. The backend is fully wired — only the desktop UI configuration panel is pending.
</Tip>

## FAQ

### Does BYOK affect tool execution?

No. Tools always execute locally on your machine regardless of which model provider is active. The model provider only affects who generates the reasoning and tool call decisions.

### Can I use a different model than the default?

Yes. Each provider supports any model ID they offer. Set it via `buildwithtrace byok model <model-id>` (CLI) or the model ID field in Settings (desktop, when available).

### What if my provider key is invalid or rate-limited?

The backend falls back to Trace-hosted models gracefully. You'll see a status message in the chat indicating the fallback occurred. Your Trace quota will be consumed for that request.

### Is my API key visible to Trace?

Your key transits through the Trace backend for the duration of one request (needed to call your provider), but it is never stored, logged, or persisted on Trace's servers.

## Next Steps

* [CLI BYOK Reference](/resources/cli-byok) — full CLI setup and commands
* [Billing & Plans](/guides/billing) — understanding Trace quota and credits
* [AI Modes](/concepts/ai-modes) — how modes interact with billing and BYOK