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 - provider requests are billed to your provider account and remain subject to its quotas, rate limits, and available balance.

Managed mode routes traffic through Rigbox’s OpenRouter gateway and meters it against your credit balance. In BYOK mode, configure your SDK or agent with your provider key and endpoint. The selected tool and endpoint determine the route; changing the workspace mode does not intercept or rewrite every outgoing SDK request.

Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account. Start the target workspace first and verify its identity with rig workspace ls. AI calls require managed credits or an appropriately configured provider account.

When to Use BYOK

BYOK is the right choice when:

You already have API keys from Anthropic, OpenAI, Google, or another provider
You want provider-billed usage instead of managed credits
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-...

Set the tool’s provider endpoint explicitly when moving from managed mode. Remove any managed base-URL overrides retained in its configuration or current shell, then restart the tool.

The API stores workspace environment changes and pushes configuration files to a running workspace. Existing processes retain their current environment; restart the affected tool or service and open a fresh login shell. Stopped workspaces receive the configuration on their next start.

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

Workspace environment values are stored in workspace metadata and written to guest configuration files, including /home/developer/.rigbox/.env. Masking CLI output does not encrypt the values or prevent workspace code from reading them. Do not treat this mechanism as a dedicated secret vault. The consuming process must load the configured provider environment variable, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or 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

Restart processes that loaded the old key. Unsetting it does not revoke the provider credential or erase copies your application already made; revoke it at the provider when needed.

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 or change a tool’s explicitly configured endpoint. Unset the key and reopen the shell or restart the tool, then verify that it uses the managed endpoint.

Mode updates refresh the workspace’s routing profile for new shells. An existing shell or process can retain old values until restarted.

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

Run rig ai defaults with no flags to see the current defaults. 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	Your account’s managed credit balance	Your provider billing
Supported providers	Models and protocols exposed by the managed gateway	Providers supported by your SDK or agent
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

Verify and troubleshoot

Inside the workspace, inspect rig proxy status, then make one small request with your chosen tool. Verify the configured endpoint and check the corresponding Rigbox or provider usage. After changing keys or mode, start a fresh shell and restart processes that retained their old configuration. Never print a provider key to verify it. For failures, start with runtime logs, health checks, or resource exhaustion.

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

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Before you begin

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

Verify and troubleshoot

Next Steps

​Before you begin

​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

​Verify and troubleshoot

​Next Steps

Before you begin

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

Verify and troubleshoot

Next Steps