Bring Your Own Keys

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.

Managed mode 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.

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

If you are just getting started or prototyping, managed mode is faster to set up - no keys needed.

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, …).

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.

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

How Keys Are Stored and Injected

When you set a BYOK key:

Stored with the workspace - the value is saved as one of the workspace’s environment variables
Masked by default - rig workspace env get shows secret-shaped values (like *_API_KEY) as <masked>; pass --reveal to print the real value
Injected at runtime - the key is exported into the workspace environment, so SDKs pick it up with no extra setup
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:

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:

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.

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

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:

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 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)

rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> ANTHROPIC_API_KEY=sk-ant-api03-...

Inside the workspace:

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)

rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> OPENAI_API_KEY=sk-proj-...

Inside the workspace:

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)

rig workspace ai mode --workspace <workspace_id> byok
rig workspace env set --workspace <workspace_id> GOOGLE_API_KEY=AIza...

Inside the workspace:

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

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.

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 - use Rigbox-provided credits instead
Setup Scripts - automate SDK installation in every workspace
Service Specs - run AI-powered backend services automatically

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

When to Use BYOK

Set BYOK Mode

How Keys Are Stored and Injected

Clear a Key

Switch Back to Managed Mode

Set Defaults for New Workspaces

Managed vs. BYOK Comparison

Provider-Specific Examples

Anthropic (Claude)

OpenAI (GPT)

Google (Gemini)

Security Best Practices

Next Steps

​When to Use BYOK

​Set BYOK Mode

​How Keys Are Stored and Injected

​Clear a Key

​Switch Back to Managed Mode

​Set Defaults for New Workspaces

​Managed vs. BYOK Comparison

​Provider-Specific Examples

​Anthropic (Claude)

​OpenAI (GPT)

​Google (Gemini)

​Security Best Practices

​Next Steps

When to Use BYOK

Set BYOK Mode

How Keys Are Stored and Injected

Clear a Key

Switch Back to Managed Mode

Set Defaults for New Workspaces

Managed vs. BYOK Comparison

Provider-Specific Examples

Anthropic (Claude)

OpenAI (GPT)

Google (Gemini)

Security Best Practices

Next Steps