You signed in with another tab or window.Reload to refresh your session.You signed out in another tab or window.Reload to refresh your session.You switched accounts on another tab or window.Reload to refresh your session.Dismiss alert
docs(ai-bridge): update configuration instructions and add support for additional providers
Revised the AI Bridge documentation to clarify provider configuration steps, including new sections for OpenAI, Anthropic, and Amazon Bedrock. Added details on pre-configuring templates and using AI Bridge with Coder Tasks. Introduced a new image illustrating the AI Bridge implementation details. Updated compatibility notes for various AI clients.Addressescoder/aibridge#4
The default base URL (`https://api.openai.com/v1/`) works for the native OpenAI service. Point the base URL at your preferred OpenAI-compatible endpoint (for example, a hosted proxy or LiteLLM deployment) when needed.
65
+
66
+
####Anthropic
67
+
68
+
Set the following when routing Anthropic-compatible traffic through Bridge:
Bridge is compatible with_[Google Vertex AI](https://cloud.google.com/vertex-ai?hl=en)_,_[AWS Bedrock](https://aws.amazon.com/bedrock/)_,andother LLM brokers. You may specify the base URL(s) above to the appropriate API endpoint for your provider.
85
+
####Additional providersandModel Proxies
72
86
73
-
---
87
+
Bridge can relay traffic to other OpenAI- or Anthropic-compatible services or model proxies like LiteLLM by pointing the base URL variables above at the provider you operate. Share feedback or follow along in the[`aibridge`](https://github.com/coder/aibridge) issue tracker as support for these providers stabilizes.
74
88
75
89
>[!NOTE]
76
-
>See[Supported APIs](#supported-apis) section below fora comprehensive list.
90
+
>Seethe[Supported APIs](#supported-apis) section below forprecise endpoint coverage and interception behavior.
77
91
78
92
##Client Configuration
79
93
80
94
Once AI Bridge is enabled on the server, your users need to configure their AI coding tools to use it. This section explains how users should configure their clients to connect to AI Bridge.
81
95
82
-
###SettingBase URLs
96
+
###Base URLs
83
97
84
98
The exact configuration method varies by client — some use environment variables, others use configuration files or UI settings:
85
99
@@ -95,43 +109,92 @@ Instead of distributing provider-specific API keys (OpenAI/Anthropic keys) to us
95
109
-**OpenAI clients**: Users set`OPENAI_API_KEY` to their Coder session token or API key
96
110
-**Anthropic clients**: Users set`ANTHROPIC_API_KEY` to their Coder session token or API key
97
111
98
-
Users can generate a Coder API key using:
112
+
####Coder Templates Pre-configuration
113
+
114
+
Template admins can pre-configure authentication in templates using[`data.coder_workspace_owner.me.session_token`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner#session_token-1) to automatically configure the workspace owner's credentials.
115
+
116
+
Here is an example of how to pre-configure a Coder template to install Claude Code and configure it for AI Bridge using the session token in a template:
claude_api_key = data.coder_workspace_owner.me.session_token # To Enable AI Bridge integration
141
+
ai_prompt = data.coder_parameter.ai_prompt.value
142
+
... # other claude-code configuration
143
+
}
99
144
100
-
```sh
101
-
coder tokens create
102
145
```
103
146
104
-
Template adminscan pre-configureauthentication in templates using[`data.coder_workspace_owner.me.session_token`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner#session_token-1) to automatically configure the workspace owner's credentials.
147
+
The same approachcanbe applied topre-configureadditional AI coding assistants by updating the base URL and API key settings.
105
148
106
-
####Compatibility Notes
149
+
####Generic API key generation
107
150
108
-
Most AI coding assistants that support custom base URLs can work with AI Bridge. However, client-specific configuration requirements vary:
151
+
Users can generate a Coder API key using either the CLI or the web UI. Follow the instructions at[Sessions and API tokens](../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself) to generate a Coder API key.
109
152
110
-
- Some clients require specific URL formats (e.g. try removing the`/v1` suffix)
111
-
- Some clients may proxy requests through their own servers, limiting compatibility (e.g. Cursor)
112
-
- Some clients may not support custom base URLs at all (e.g. Copilot CLI, Sourcegraph Amp)
153
+
###Tested clients
113
154
114
-
Consult yourspecificAIclient's documentation for details on configuring custom API endpoints.
155
+
The combinations below reflect what we have exercised so far. Use the upstream links for vendor-specificsteps to point eachclient at Bridge. Share additional findings in the[`aibridge`](https://github.com/coder/aibridge) issue tracker so we can keep this table current.
|[Roo Code (VS Code)](https://github.com/RooVetGit/Roo-Code#configuration)| ✅| ✅| Use the**OpenAI Compatible** provider with the legacy format to avoid`/v1/responses`. Some MCP tools (for example`star_github_repository`) may require additional permissions.|
|[Claude Code (VS Code)](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-vscode)| N/A| ✅| May require signing in once; afterwards respects workspace environment variables.|
164
+
|[Cursor](https://cursor.com/docs/settings/api-keys)| ⚠️| ❌| Only non reasoning models like`gpt-4.1` are available when using a custom endpoint. Requests still transit Cursor's cloud. There is no central admin setting to configure this.|
165
+
| WindSurf| ❌| —| No option to override the base URL.|
166
+
| Sourcegraph Amp| ❌| —| No option to override the base URL.|
167
+
| Codex CLI| ⚠️| N/A|`gpt-5-codex` support is[in progress](https://github.com/coder/aibridge/issues/16).|
168
+
|[GitHub Copilot (VS Code)](https://code.visualstudio.com/docs/copilot/customization/language-models#_use-an-openaicompatible-model)| ✅| ❌| Only OpenAI-compatible models are supported.|
169
+
| Kiro| ❌| —| No option to override the base URL.|
170
+
|[Copilot CLI](https://github.com/github/copilot-cli/issues/104)| ❌| ❌| Cannot override the base URL and use a`GITHUB_TOKEN` for authentication.|
| Gemini CLI| ❌| ❌| Not supported yet (`GOOGLE_GEMINI_BASE_URL`).|
173
+
|[Amazon Q CLI](https://aws.amazon.com/q/)| ❌| ❌| Limited to Amazon Q subscriptions; no custom endpoint support.|
117
174
118
-
Bridge collects:
175
+
Legend: ✅ works, ⚠️ limited support, ❌ not supported, ❓ not yet verified, — not applicable.
119
176
120
-
- The last`user` prompt of each request
121
-
- All token usage (associated with each prompt)
122
-
- Every tool invocation
177
+
####Compatibility overview
123
178
124
-
All of these records are associated to an "interception" record, which maps 1:1withrequests received from clients but may involve several interactions with upstream providers. Interceptions are associated with a Coder identity, allowing you to map consumption and cost with teams or individuals in your organization:
179
+
Most AI coding assistants that support custom base URLs can workwithAI Bridge. Client-specific requirements vary:
- Some clients require specific URL formats (for example, removing the`/v1` suffix).
182
+
- Some clients proxy requests through their own servers, which limits compatibility.
183
+
- Some clients do not support custom base URLs.
127
184
128
-
These logs can be used to determine usage patterns, track costs,andevaluate tooling adoption.
185
+
See the[tested clients](#tested-clients) table above for the combinations we have verifiedandany known issues.
129
186
130
-
This data is currently accessible through the API and CLI, which we advise administrators export to their observability platform of choice. We've configured a Grafana dashboard to display Claude Code usage internally which can be imported as a starting point for your tooling adoption metrics.
187
+
##Request logs
188
+
189
+
Bridge records the last`user` prompt, token usage, and every tool invocation for each intercepted request. Each capture is tied to a single "interception" that maps back to the authenticated Coder identity, making it easy to attribute spend and behaviour.
We provide an example Grafana dashboard that you can import as a starting point for your tooling adoption metrics. See[here](https://github.com/coder/coder/blob/main/examples/monitoring/dashboards/grafana/aibridge/README.md).
195
+
We provide an example Grafana dashboard that you can import as a starting point for your metrics. See[the Grafana dashboard README](https://github.com/coder/coder/blob/main/examples/monitoring/dashboards/grafana/aibridge/README.md).
196
+
197
+
These logs and metrics can be used to determine usage patterns, track costs, and evaluate tooling adoption.
@@ -244,6 +309,20 @@ In the above example, if you prompted your AI model with "list your available gi
244
309
245
310
Bridge marks automatically injected tools with a prefix`bmcp_` ("bridged MCP"). It also namespaces all tool names by the ID of their associated External Auth application (in this case`github`).
246
311
312
+
##Using AI Bridge with Coder Tasks
313
+
314
+
[Coder Tasks](./tasks.md) provides a chat-first interface for terminal agents such as Claude Code CLI or Codex. To route those agents through Bridge:
315
+
316
+
- Enable Bridge at the control plane and configure the upstream provider keys.
317
+
- Inject the AI Bridge base URLs and API keys into the Task environment (for example by setting`OPENAI_BASE_URL` and`OPENAI_API_KEY`).
318
+
- Template authors can bake these variables into Task definitions so that new runs automatically use Bridge.
319
+
320
+
This setup keeps agent execution within Coder while applying the same auditing and MCP policies as IDE clients.
321
+
322
+
##Using AI Bridge without Tasks
323
+
324
+
Bridge also works with IDE-native assistants inside workspaces. Configure the IDE extension or desktop client to point at the Bridge endpoints and rely on the workspace's environment variables for authentication. This is the fastest path to bring existing agents like Roo Code, Cursor, or Claude Code into compliance without adopting Tasks.
325
+
247
326
##Tool Injection
248
327
249
328
If a model decides to invoke a tool and it has a`bmcp_` suffix and Bridge has a connection with the related MCP server, it will invoke the tool. The tool result will be passed back to the upstream AI provider, and this will loop until the model has all of its required data. These inner loops are not relayed back to the client; all it seems is the result of this loop. See[Implementation Details](#implementation-details).
@@ -262,7 +341,7 @@ If you have the `oauth2` and `mcp-server-http` experiments enabled, Coder's own
262
341
263
342
##Known Issues / Limitations
264
343
265
-
- CodexCLIcurrently does not work with Bridge due toa JSON marshaling issue:https://github.com/coder/aibridge/issues/19
344
+
-GPT-5Codex currently does not work with Bridge due tomissing`v1/responses` endpoint:https://github.com/coder/aibridge/issues/16
266
345
- Claude Code web searches do not report correctly:https://github.com/coder/aibridge/issues/11