diff --git a/docs/ai-coder/ai-bridge/clients/claude-code.md b/docs/ai-coder/ai-bridge/clients/claude-code.md index e938a080b8..7f0dc01e54 100644 --- a/docs/ai-coder/ai-bridge/clients/claude-code.md +++ b/docs/ai-coder/ai-bridge/clients/claude-code.md @@ -1,13 +1,50 @@ # Claude Code -## Configuration +Claude Code can be configured using environment variables. All modes require a **[Coder session token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)** for authentication with AI Bridge. -Claude Code can be configured using environment variables. +## Centralized API Key -* **Base URL**: `ANTHROPIC_BASE_URL` should point to `https://coder.example.com/api/v2/aibridge/anthropic` -* **Auth Token**: `ANTHROPIC_AUTH_TOKEN` should be your [Coder session token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself). +```bash +# AI Bridge base URL. +export ANTHROPIC_BASE_URL="/api/v2/aibridge/anthropic" -### Pre-configuring in Templates +# Your Coder session token, used for authentication with AI Bridge. +export ANTHROPIC_AUTH_TOKEN="" +``` + +## BYOK (Personal API Key) + +```bash +# AI Bridge base URL. +export ANTHROPIC_BASE_URL="/api/v2/aibridge/anthropic" + +# Your personal Anthropic API key, forwarded to Anthropic. +export ANTHROPIC_API_KEY="" + +# Your Coder session token, used for authentication with AI Bridge. +export ANTHROPIC_CUSTOM_HEADERS="X-Coder-AI-Governance-Token: " + +# Ensure no auth token is set so Claude Code uses the API key instead. +unset ANTHROPIC_AUTH_TOKEN +``` + +## BYOK (Claude Subscription) + +```bash +# AI Bridge base URL. +export ANTHROPIC_BASE_URL="/api/v2/aibridge/anthropic" + +# Your Coder session token, used for authentication with AI Bridge. +export ANTHROPIC_CUSTOM_HEADERS="X-Coder-AI-Governance-Token: " + +# Ensure no auth token is set so Claude Code uses subscription login instead. +unset ANTHROPIC_AUTH_TOKEN +``` + +When you run Claude Code, it will prompt you to log in with your Anthropic +account. + +## Pre-configuring in Templates Template admins can pre-configure Claude Code for a seamless experience. Admins can automatically inject the user's Coder session token and the AI Bridge base URL into the workspace environment. diff --git a/docs/ai-coder/ai-bridge/clients/codex.md b/docs/ai-coder/ai-bridge/clients/codex.md index c935fe4519..00f0811fe7 100644 --- a/docs/ai-coder/ai-bridge/clients/codex.md +++ b/docs/ai-coder/ai-bridge/clients/codex.md @@ -2,7 +2,7 @@ Codex CLI can be configured to use AI Bridge by setting up a custom model provider. -## Configuration +## Centralized API Key To configure Codex CLI to use AI Bridge, set the following configuration options in your Codex configuration file (e.g., `~/.codex/config.toml`): @@ -16,9 +16,73 @@ env_key = "OPENAI_API_KEY" wire_api = "responses" ``` -Run Codex as usual. It will automatically use the `aibridge` model provider from your configuration: +To authenticate with AI Bridge, get your **[Coder session token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)** and set it in your environment: -If configuring within a Coder workspace, you can also use the [Codex CLI](https://registry.coder.com/modules/coder-labs/codex) module and set the following variables: +```bash +export OPENAI_API_KEY="" +``` + +Run Codex as usual. It will automatically use the `aibridge` model provider from your configuration. + +## BYOK (Personal API Key) + +Add the following to your Codex configuration file (e.g., `~/.codex/config.toml`): + +```toml +model_provider = "aibridge" + +[model_providers.aibridge] +name = "AI Bridge" +base_url = "/api/v2/aibridge/openai/v1" +wire_api = "responses" +requires_openai_auth = true +env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_SESSION_TOKEN" } +``` + +Set both environment variables: + +```bash +# Your personal OpenAI API key, forwarded to OpenAI. +export OPENAI_API_KEY="" + +# Your Coder session token, used for authentication with AI Bridge. +export CODER_SESSION_TOKEN="" +``` + +## BYOK (ChatGPT Subscription) + +Add the following to your Codex configuration file (e.g., `~/.codex/config.toml`): + +```toml +model_provider = "aibridge" + +[model_providers.aibridge] +name = "AI Bridge" +base_url = "/api/v2/aibridge/chatgpt/v1" +wire_api = "responses" +requires_openai_auth = true +env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_SESSION_TOKEN" } +``` + +> [!NOTE] +> The `base_url` uses `/aibridge/chatgpt/v1` instead of `/aibridge/openai/v1` to route requests through the ChatGPT provider. + +Set your Coder session token and ensure `OPENAI_API_KEY` is not set: + +```bash +# Your Coder session token, used for authentication with AI Bridge. +export CODER_SESSION_TOKEN="" + +# Ensure no OpenAI API key is set so Codex uses ChatGPT login instead. +unset OPENAI_API_KEY +``` + +When you run Codex, it will prompt you to log in with your ChatGPT account. + +## Pre-configuring in Templates + +If configuring within a Coder workspace, you can use the +[Codex CLI](https://registry.coder.com/modules/coder-labs/codex) module: ```tf module "codex" { @@ -30,12 +94,4 @@ module "codex" { } ``` -## Authentication - -To authenticate with AI Bridge, get your **[Coder session token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)** and set it in your environment: - -```bash -export OPENAI_API_KEY="" -``` - **References:** [Codex CLI Configuration](https://developers.openai.com/codex/config-advanced) diff --git a/docs/ai-coder/ai-bridge/clients/index.md b/docs/ai-coder/ai-bridge/clients/index.md index 7c99b5f3d3..db717bc74c 100644 --- a/docs/ai-coder/ai-bridge/clients/index.md +++ b/docs/ai-coder/ai-bridge/clients/index.md @@ -43,6 +43,29 @@ export ANTHROPIC_BASE_URL="https://coder.example.com/api/v2/aibridge/anthropic" Alternatively, [generate a long-lived API token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself) via the Coder dashboard. +## Bring Your Own Key (BYOK) + +In addition to centralized key management, AI Bridge supports **Bring Your +Own Key** (BYOK) mode. Users can provide their own LLM API keys or use +provider subscriptions (such as Claude Pro/Max or ChatGPT Plus/Pro) while +AI Bridge continues to provide observability and governance. + +![BYOK authentication flow](../../../images/aibridge/clients/byok_auth_flow.png) + +In BYOK mode, users need two credentials: + +- A **Coder session token** to authenticate with AI Bridge. +- Their **own LLM credential** (personal API key or subscription token) which AI Bridge forwards + to the upstream provider. + +BYOK and centralized modes can be used together. When a user provides +their own credential, AI Bridge forwards it directly. When no user +credential is present, AI Bridge falls back to the admin-configured +provider key. This lets organizations offer centralized keys as a default +while allowing individual users to bring their own. + +See individual client pages for configuration details. + ## Compatibility The table below shows tested AI clients and their compatibility with AI Bridge. diff --git a/docs/images/aibridge/clients/byok_auth_flow.png b/docs/images/aibridge/clients/byok_auth_flow.png new file mode 100644 index 0000000000..1af4e55f8a Binary files /dev/null and b/docs/images/aibridge/clients/byok_auth_flow.png differ