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

# Bring Your Own Keys

> Use your own AI provider API keys instead of Rigbox-managed credits.

Bring Your Own Keys (BYOK) mode lets you use your own AI provider API keys with Rigbox workspaces. You set the workspace to BYOK mode and provide your provider key as a workspace environment variable - you get unlimited usage billed directly by your provider, with no Rigbox credit limits.

<Note>
  [Managed mode](/guides/managed-proxy) routes traffic through Rigbox's OpenRouter gateway and meters it against your credit balance. BYOK skips OpenRouter entirely and connects your workspace directly to the provider you specify, using the key you supply.
</Note>

## When to Use BYOK

BYOK is the right choice when:

* **You already have API keys** from Anthropic, OpenAI, Google, or another provider
* **You need unlimited usage** beyond the managed credit tiers
* **You need a specific model** not available in managed mode
* **Your organization requires** that API keys stay under your own provider account for billing, audit, or compliance reasons

<Tip>
  If you are just getting started or prototyping, [managed mode](/guides/managed-proxy) is faster to set up - no keys needed.
</Tip>

## Set BYOK Mode

BYOK is two steps: flip the workspace's AI mode to `byok`, then set your provider key as a workspace environment variable using the standard name your SDK expects (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, …).

```bash theme={null}
rig workspace ai mode --workspace <workspace_id> byok

rig workspace env set --workspace <workspace_id> ANTHROPIC_API_KEY=sk-ant-...
```

Rigbox detects BYOK from the presence of a provider key in the workspace environment and routes your code straight to that provider, bypassing the managed proxy.

<Note>
  Environment changes apply on the next workspace start. Restart the workspace (`rig workspace stop` then `rig workspace start`) if it is already running.
</Note>

## How Keys Are Stored and Injected

When you set a BYOK key:

1. **Stored with the workspace** - the value is saved as one of the workspace's environment variables
2. **Masked by default** - `rig workspace env get` shows secret-shaped values (like `*_API_KEY`) as `<masked>`; pass `--reveal` to print the real value
3. **Injected at runtime** - the key is exported into the workspace environment, so SDKs pick it up with no extra setup
4. **Scoped to the workspace** - each workspace has its own environment; changing one does not affect others

The key is available inside the workspace as the standard environment variable for the provider SDK (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`).

## Clear a Key

To remove a provider key from a workspace, unset the environment variable:

```bash theme={null}
rig workspace env unset --workspace <workspace_id> ANTHROPIC_API_KEY
```

The workspace will no longer have access to the provider until you set a new key.

## Switch Back to Managed Mode

You can switch from BYOK to managed mode at any time. This starts routing through Rigbox-managed credits again:

```bash theme={null}
rig workspace ai mode --workspace <workspace_id> managed
```

Switching the mode does not delete your provider key — managed mode simply injects its own credentials and ignores it. To fully remove the key, unset the environment variable as shown above.

<Note>
  Mode changes take effect on the next AI API call. A new provider key requires a workspace restart to be injected.
</Note>

## Set Defaults for New Workspaces

If you use BYOK across most of your workspaces, set an account default so new workspaces start in BYOK mode with your preferred provider and model:

```bash theme={null}
rig ai defaults --mode byok --provider anthropic --model claude-sonnet-4-20250514
```

Account defaults cover mode, provider, and model only — the provider **key** is always set per workspace (with `rig workspace env set`), so it is never stored account-wide. See the [AI Defaults API reference](/api-reference/ai/update-defaults) for the full schema.

## Managed vs. BYOK Comparison

| Feature             | Managed                                  | BYOK                                     |
| ------------------- | ---------------------------------------- | ---------------------------------------- |
| API keys required   | No                                       | Yes                                      |
| Credit tracking     | Automatic                                | N/A (billed by your provider)            |
| Cost                | Included credits (Free: 250, Pro: 2,000) | Your provider billing                    |
| Supported providers | Anthropic, OpenAI, Google, Brave         | Any supported provider                   |
| Usage limits        | Credit balance                           | Your provider's rate limits              |
| Setup time          | Instant                                  | Need existing API key                    |
| Best for            | Quick start, prototyping, demos          | Production, high volume, specific models |

## Provider-Specific Examples

### Anthropic (Claude)

```bash theme={null}
rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> ANTHROPIC_API_KEY=sk-ant-api03-...
```

Inside the workspace:

```python theme={null}
from anthropic import Anthropic

# ANTHROPIC_API_KEY is injected automatically
client = Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}]
)
print(message.content[0].text)
```

### OpenAI (GPT)

```bash theme={null}
rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> OPENAI_API_KEY=sk-proj-...
```

Inside the workspace:

```python theme={null}
from openai import OpenAI

# OPENAI_API_KEY is injected automatically
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, GPT!"}]
)
print(response.choices[0].message.content)
```

### Google (Gemini)

```bash theme={null}
rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> GOOGLE_API_KEY=AIza...
```

Inside the workspace:

```python theme={null}
import google.generativeai as genai

# GOOGLE_API_KEY is injected automatically
model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content("Hello, Gemini!")
print(response.text)
```

## Security Best Practices

<Warning>
  Set provider keys with `rig workspace env set`, not by hardcoding them in your code or committing a `.env` file to your repo. The CLI keeps the value in the workspace environment and masks it in `rig workspace env get` by default.
</Warning>

* **Rotate keys regularly** - update the key with `rig workspace env set`, then restart the workspace
* **Use scoped keys** - if your provider supports project-scoped or restricted keys, prefer those over organization-wide keys
* **Audit usage** - monitor your provider dashboard for unexpected usage patterns
* **One key per workspace** - avoid sharing the same key across many workspaces; this makes it easier to revoke access to a single workspace

## Next Steps

* [Managed AI Proxy](/guides/managed-proxy) - use Rigbox-provided credits instead
* [Setup Scripts](/guides/setup-scripts) - automate SDK installation in every workspace
* [Service Specs](/guides/service-specs) - run AI-powered backend services automatically