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

# Bring Your Own Key (BYOK)

> Use your own LLM API keys with orchagent

orchagent uses a **Bring Your Own Key** model. You provide your own LLM API keys, and agents use them to make LLM calls.

<Info>
  **When BYOK applies:** BYOK is relevant for `orch run` (cloud execution, the default) and `orch run --local` (local execution). For `orch install`, no LLM keys are needed since you're just exporting configuration files.
</Info>

## Why BYOK?

| Benefit                | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| **Authors don't pay**  | Agent authors don't pay for others' usage                 |
| **No markup**          | Direct relationship with LLM provider, no middleman costs |
| **Your limits**        | Use your existing rate limits and quotas                  |
| **Your data policies** | LLM calls go through your account                         |

<Note>
  **API keys are separate from subscriptions.** If you use Claude Pro/Max or ChatGPT Plus, you'll need to set up API billing separately. Get API keys at [console.anthropic.com](https://console.anthropic.com) or [platform.openai.com](https://platform.openai.com).
</Note>

## Key Resolution Order

When an agent needs an LLM key, it looks in this order:

1. **Command-line flag** — `--key` on CLI commands
2. **Environment variable** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc. (local execution)
3. **Workspace secrets vault** — keys stored in your workspace (server execution)

LLM keys are stored as regular workspace secrets with conventional names (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`). The platform matches these names automatically.

## Setting Up Keys

### For Local Execution

Set environment variables:

```bash theme={null}
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Google Gemini
export GEMINI_API_KEY="..."
```

Then run agents locally:

```bash theme={null}
orch run --local acme/summarizer --input '{"text": "..."}'
```

### For Server Execution

Store keys in your workspace secrets vault:

```bash theme={null}
# Add your LLM API key to the workspace vault
orch secrets set ANTHROPIC_API_KEY sk-ant-...

# Or for OpenAI
orch secrets set OPENAI_API_KEY sk-...
```

Or add them in the [dashboard](https://orchagent.io/dashboard) under Settings → Secrets.

Then run agents on the cloud:

```bash theme={null}
orch run acme/summarizer --data '{"text": "..."}'
```

## Supported Providers

| Provider      | Environment Variable | API Endpoint                                       |
| ------------- | -------------------- | -------------------------------------------------- |
| OpenAI        | `OPENAI_API_KEY`     | `https://api.openai.com/v1`                        |
| Anthropic     | `ANTHROPIC_API_KEY`  | `https://api.anthropic.com`                        |
| Google Gemini | `GEMINI_API_KEY`     | `https://generativelanguage.googleapis.com`        |
| Ollama        | N/A                  | `http://localhost:11434/v1` (local execution only) |

## Agent Provider Requirements

Agents specify which providers they support in their manifest:

```json theme={null}
{
  "supported_providers": ["openai", "anthropic"]
}
```

You need a key for at least one supported provider.

### Provider Values

| Value       | Description                                  |
| ----------- | -------------------------------------------- |
| `openai`    | OpenAI API                                   |
| `anthropic` | Anthropic API                                |
| `gemini`    | Google Gemini API                            |
| `any`       | Works with any provider                      |
| `ollama`    | Local Ollama instance (local execution only) |

## Fallback Configuration

For code runtime agents, authors can specify fallback LLMs:

```yaml theme={null}
llm:
  primary: gemini-2.5-flash
  fallbacks:
    - gpt-4o-mini
    - claude-3-haiku
```

The agent tries providers in order until one succeeds.

## Security

### Local Execution

Keys stay on your machine. The agent runs locally and makes LLM calls directly from your environment.

### Server Execution

Keys are encrypted and stored in your workspace vault. They're injected into the agent's sandbox at runtime.

<Note>
  Agent containers run in isolated environments. Your keys are never exposed to agent authors.
</Note>

### Network Egress Controls

Server-executed agents route all outbound traffic through an allowlist proxy:

**Allowed destinations:**

* LLM APIs (OpenAI, Anthropic, Gemini)
* orchagent gateway (`api.orchagent.io`)
* Other orchagent agents

**Blocked:**

* All other domains
* Private IP ranges
* Cloud metadata endpoints

## Best Practices

1. **Use environment variables** for local development
2. **Store keys in workspace vault** for server execution (`orch secrets set` or dashboard)
3. **Set spending limits** with your LLM provider
4. **Rotate keys regularly** if you share them
5. **Use separate keys** for development and production