From e3f78500e75986220714160ec87cbf36e18e9452 Mon Sep 17 00:00:00 2001 From: Susana Ferreira Date: Thu, 5 Feb 2026 16:54:26 +0000 Subject: [PATCH] docs: add AI Bridge Proxy client configuration (#21904) ## Description This PR adds documentation for configuring clients to work with AI Bridge via AI Bridge Proxy, specifically GitHub Copilot. Preview: https://coder.com/docs/@docs-aibridge-proxy-client-config/ai-coder/ai-bridge/ai-bridge-proxy/setup#client-configuration ## Changes * Add Client Configuration section to `docs/ai-coder/ai-bridge/ai-bridge-proxy/setup.md` covering proxy and CA certificate configuration * Add `docs/ai-coder/ai-bridge/clients/copilot.md` with configuration instructions for: Copilot CLI, VS Code Copilot Extension, JetBrains IDEs * Update `docs/ai-coder/ai-bridge/clients/index.md`: * Add introduction explaining base URL vs proxy-based integration * Add GitHub Copilot to compatibility table Related to: https://github.com/coder/internal/issues/1188 --- .../ai-bridge/ai-bridge-proxy/index.md | 1 - .../ai-bridge/ai-bridge-proxy/setup.md | 94 +++++++++++- docs/ai-coder/ai-bridge/clients/copilot.md | 136 ++++++++++++++++++ docs/ai-coder/ai-bridge/clients/index.md | 8 +- docs/manifest.json | 5 + 5 files changed, 238 insertions(+), 6 deletions(-) create mode 100644 docs/ai-coder/ai-bridge/clients/copilot.md diff --git a/docs/ai-coder/ai-bridge/ai-bridge-proxy/index.md b/docs/ai-coder/ai-bridge/ai-bridge-proxy/index.md index 95d9d871fe..96bf0adacb 100644 --- a/docs/ai-coder/ai-bridge/ai-bridge-proxy/index.md +++ b/docs/ai-coder/ai-bridge/ai-bridge-proxy/index.md @@ -33,4 +33,3 @@ Nevertheless, clients with base URL overrides also work with the proxy, in case ## Next steps * [Set up AI Bridge Proxy](./setup.md) on your Coder deployment -* [Troubleshoot](./setup.md) common issues diff --git a/docs/ai-coder/ai-bridge/ai-bridge-proxy/setup.md b/docs/ai-coder/ai-bridge/ai-bridge-proxy/setup.md index 08d41539f0..2bccdc5cdb 100644 --- a/docs/ai-coder/ai-bridge/ai-bridge-proxy/setup.md +++ b/docs/ai-coder/ai-bridge/ai-bridge-proxy/setup.md @@ -7,7 +7,7 @@ Once enabled, `coderd` runs the `aibridgeproxyd` in-memory and intercepts traffi 1. AI Bridge must be enabled and configured (requires a **Premium** license with the [AI Governance Add-On](../../ai-governance.md)). See [AI Bridge Setup](../setup.md) for further information.1. AI Bridge Proxy must be [enabled](#proxy-configuration) using the server flag. 1. A [CA certificate](#ca-certificate) must be configured for MITM interception. -1. Clients must be configured to trust the CA certificate and use the proxy. +1. [Clients](#client-configuration) must be configured to use the proxy and trust the CA certificate. > [!WARNING] > AI Bridge Proxy should only be accessible within a trusted network and **must not** be directly exposed to the public internet. @@ -112,7 +112,7 @@ CODER_AIBRIDGE_PROXY_CERT_FILE=/path/to/ca.crt CODER_AIBRIDGE_PROXY_KEY_FILE=/path/to/ca.key ``` -### Organization-signed certificate +### Corporate CA certificate If your organization has an internal CA that clients already trust, you can have it issue an intermediate CA certificate for AI Bridge Proxy. This simplifies deployment since AI tools that already trust your organization's root CA will automatically trust certificates signed by the intermediate. @@ -145,10 +145,10 @@ For **self-signed certificates**, AI tools must be configured to trust the CA ce https:///api/v2/aibridge/proxy/ca-cert.pem ``` -For **organization-signed certificates**, if the systems where AI tools run already trust your organization's root CA, and the intermediate certificate chains correctly to that root, no additional certificate distribution is needed. +For **corporate CA certificates**, if the systems where AI tools run already trust your organization's root CA, and the intermediate certificate chains correctly to that root, no additional certificate distribution is needed. Otherwise, AI tools must be configured to trust the intermediate CA certificate from the endpoint above. -How you configure AI tools to trust the certificate depends on the tool and operating system. See Client Configuration for details. +How you configure AI tools to trust the certificate depends on the tool and operating system. See [Client Configuration](#client-configuration) for details. ## Upstream proxy @@ -187,3 +187,89 @@ If the system already trusts the upstream proxy's CA certificate, [`CODER_AIBRID + +## Client Configuration + +To use AI Bridge Proxy, AI tools must be configured to: + +1. Route traffic through the proxy +1. Trust the proxy's CA certificate + +### Configuring the proxy + +The preferred approach is to configure the proxy directly in the AI tool's settings, as this avoids routing unnecessary traffic through the proxy. +Consult the tool's documentation for specific instructions. + +Alternatively, most tools support the standard proxy environment variables, though this is not guaranteed for all tools: + +```shell +export HTTP_PROXY="http://coder:${CODER_SESSION_TOKEN}@:8888" +export HTTPS_PROXY="http://coder:${CODER_SESSION_TOKEN}@:8888" +``` + +* `HTTP_PROXY`: Used for requests to `http://` URLs +* `HTTPS_PROXY`: Used for requests to `https://` URLs (this is the one used for AI provider domains) + +In order for AI tools that communicate with AI Bridge Proxy to authenticate with Coder via AI Bridge, the Coder session token needs to be passed in the proxy credentials as the password field. + +### Trusting the CA certificate + +The preferred approach is to configure the CA certificate directly in the AI tool's settings, as this limits the scope of the trusted certificate to that specific application. +Consult the tool's documentation for specific instructions. + +> [!NOTE] +> If using a [corporate CA certificate](#corporate-ca-certificate) and the system already trusts your organization's root CA, no additional certificate configuration is required. + +Download the certificate: + +```shell +curl -o coder-aibridge-proxy-ca.pem \ + -H "Coder-Session-Token: ${CODER_SESSION_TOKEN}" \ + https:///api/v2/aibridge/proxy/ca-cert.pem +``` + +Replace `` with your Coder deployment URL. + +#### Environment variables + +Different AI tools use different runtimes, each with their own environment variable for CA certificates: + +| Environment Variable | Runtime | +|-----------------------|---------------------------| +| `NODE_EXTRA_CA_CERTS` | Node.js | +| `SSL_CERT_FILE` | OpenSSL, Python, curl | +| `REQUESTS_CA_BUNDLE` | Python `requests` library | +| `CURL_CA_BUNDLE` | curl | + +Set the environment variables associated with the AI tool's runtime. +If you're unsure which runtime the tool uses, or if you use multiple AI tools, the simplest approach is to set all of them: + +```shell +export NODE_EXTRA_CA_CERTS="/path/to/coder-aibridge-proxy-ca.pem" +export SSL_CERT_FILE="/path/to/coder-aibridge-proxy-ca.pem" +export REQUESTS_CA_BUNDLE="/path/to/coder-aibridge-proxy-ca.pem" +export CURL_CA_BUNDLE="/path/to/coder-aibridge-proxy-ca.pem" +``` + +#### System trust store + +When tool-specific or environment variable configuration is not possible, you can add the certificate to the system trust store. +This makes the certificate trusted by all applications on the system. + +On Linux: + +```shell +sudo cp coder-aibridge-proxy-ca.pem /usr/local/share/ca-certificates/ +sudo update-ca-certificates +``` + +For other operating systems, refer to the system's documentation for instructions on adding trusted certificates. + +### Coder workspaces + +For AI tools running inside Coder workspaces, template administrators can pre-configure the proxy settings and CA certificate in the workspace template. +This provides a seamless experience where users don't need to configure anything manually. + + + +For tool-specific configuration details, check the [client compatibility table](../clients/index.md#compatibility) for clients that require proxy-based integration. diff --git a/docs/ai-coder/ai-bridge/clients/copilot.md b/docs/ai-coder/ai-bridge/clients/copilot.md new file mode 100644 index 0000000000..65a916130e --- /dev/null +++ b/docs/ai-coder/ai-bridge/clients/copilot.md @@ -0,0 +1,136 @@ +# GitHub Copilot + +[GitHub Copilot](https://github.com/features/copilot) is an AI coding assistant that doesn't support custom base URLs but does respect proxy configurations. +This makes it compatible with [AI Bridge Proxy](../ai-bridge-proxy/index.md), which integrates with [AI Bridge](../index.md) for full access to auditing and governance features. +To use Copilot with AI Bridge, make sure AI Bridge Proxy is properly configured, see [AI Bridge Proxy Setup](../ai-bridge-proxy/setup.md) for instructions. + +Copilot uses **per-user tokens** tied to GitHub accounts rather than a shared API key. +Users must still authenticate with GitHub to use Copilot. + +For general information about GitHub Copilot, see the [GitHub Copilot documentation](https://docs.github.com/en/copilot). + +For general client configuration requirements, see [AI Bridge Proxy Client Configuration](../ai-bridge-proxy/setup.md#client-configuration). +The sections below cover Copilot-specific setup for each client. + +## Copilot CLI + +For installation instructions, see [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/install-copilot-cli). + +### Proxy configuration + +Set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables: + +```shell +export HTTP_PROXY="http://coder:${CODER_SESSION_TOKEN}@:8888" +export HTTPS_PROXY="http://coder:${CODER_SESSION_TOKEN}@:8888" +``` + +Replace `` with your AI Bridge Proxy hostname. + +### CA certificate trust + +Copilot CLI is built on Node.js and uses the `NODE_EXTRA_CA_CERTS` environment variable for custom certificates: + +```shell +export NODE_EXTRA_CA_CERTS="/path/to/coder-aibridge-proxy-ca.pem" +``` + +See [Client Configuration CA certificate trust](../ai-bridge-proxy/setup.md#trusting-the-ca-certificate) for details on how to obtain the certificate file. + +## VS Code Copilot Extension + +For installation instructions, see [Installing the GitHub Copilot extension in VS Code](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-extension?tool=vscode). + +### Proxy configuration + +You can configure the proxy using environment variables or VS Code settings. +For environment variables, see [AI Bridge Proxy client configuration](../ai-bridge-proxy/setup.md#configuring-the-proxy). + +Alternatively, you can configure the proxy directly in VS Code settings: + +1. Open Settings (`Ctrl+,` for Windows or `Cmd+,` for macOS) +1. Search for `HTTP: Proxy` +1. Set the proxy URL using the format `http://coder:@:8888` + +Or add directly to your `settings.json`: + +```json +{ + "http.proxy": "http://coder:@:8888" +} +``` + +The `http.proxy` setting is used for both HTTP and HTTPS requests. +Replace `` with your AI Bridge Proxy hostname and `` with your coder session token. + +Restart VS Code for changes to take effect. + +For more details, see [Configuring proxy settings for Copilot](https://docs.github.com/en/copilot/how-tos/configure-personal-settings/configure-network-settings?tool=vscode) in the GitHub documentation. + +### CA certificate trust + +Add the AI Bridge Proxy CA certificate to your operating system's trust store. +By default, VS Code loads system certificates, controlled by the `http.systemCertificates` setting. + +See [Client Configuration CA certificate trust](../ai-bridge-proxy/setup.md#trusting-the-ca-certificate) for details on how to obtain the certificate file. + +### Using Coder Remote extension + +When connecting to a Coder workspace with the [Coder extension](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote), the Copilot extension runs inside the Coder workspace and not on your local machine. +This means proxy and certificate configuration must be done in the Coder workspace environment. + +#### Proxy configuration + +Configure the proxy in VS Code's remote settings: + +1. [Connect to your Coder workspace](../../../user-guides/workspace-access/vscode.md) +1. Open Settings (`Ctrl+,` for Windows or `Cmd+,` for macOS) +1. Select the **Remote** tab +1. Search for `HTTP: Proxy` +1. Set the proxy URL using the format `http://coder:@:8888` + +Replace `` with your AI Bridge Proxy hostname and `` with your coder session token. + +#### CA certificate trust + +Since the Copilot extension runs inside the Coder workspace, add the [AI Bridge Proxy CA certificate](../ai-bridge-proxy/setup.md#trusting-the-ca-certificate) to the Coder workspace's system trust store. +See [System trust store](../ai-bridge-proxy/setup.md#system-trust-store) for instructions on how to do this on Linux. + +Restart VS Code for changes to take effect. + +## JetBrains IDEs + +For installation instructions, see [Installing the GitHub Copilot extension in JetBrains IDE](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-extension?tool=jetbrains). + +### Proxy configuration + +Configure the proxy directly in JetBrains IDE settings: + +1. Open Settings (`Ctrl+Alt+S` for Windows or `Cmd+,` for macOS) +1. Navigate to `Appearance & Behavior` > `System Settings` > `HTTP Proxy` +1. Select `Manual proxy configuration` and `HTTP` +1. Enter the proxy hostname and port (default: 8888) +1. Select `Proxy authentication` and enter: + 1. Login: `coder` (this value is ignored) + 1. Password: Your Coder session token + 1. Check `Remember` to save the password +1. Restart the IDE for changes to take effect + +For more details, see [Configuring proxy settings for Copilot](https://docs.github.com/en/copilot/how-tos/configure-personal-settings/configure-network-settings?tool=jetbrains) in the GitHub documentation. + +### CA certificate trust + +Add the AI Bridge Proxy CA certificate to your operating system's trust store. +If the certificate is in the system trust store, no additional IDE configuration is needed. + +Alternatively, you can configure the IDE to accept the certificate: + +1. Open Settings (`Ctrl+Alt+S` for Windows or `Cmd+,` for macOS) +1. Navigate to `Appearance & Behavior` > `System Settings` > `Server Certificates` +1. Under `Accepted certificates`, click `+` and select the CA certificate file +1. Check `Accept non-trusted certificates automatically` +1. Restart the IDE for changes to take effect + +For more details, see [Trusted root certificates](https://www.jetbrains.com/help/idea/ssl-certificates.html) in the JetBrains documentation. + +See [Client Configuration CA certificate trust](../ai-bridge-proxy/setup.md#trusting-the-ca-certificate) for details on how to obtain the certificate file. diff --git a/docs/ai-coder/ai-bridge/clients/index.md b/docs/ai-coder/ai-bridge/clients/index.md index 94a1357270..7c99b5f3d3 100644 --- a/docs/ai-coder/ai-bridge/clients/index.md +++ b/docs/ai-coder/ai-bridge/clients/index.md @@ -2,6 +2,11 @@ Once AI Bridge is setup on your deployment, the AI coding tools used by your users will need to be configured to route requests via AI Bridge. +There are two ways to connect AI tools to AI Bridge: + +- Base URL configuration (Recommended): Most AI tools allow customizing the base URL for API requests. This is the preferred approach when supported. +- AI Bridge Proxy: For tools that don't support base URL configuration, [AI Bridge Proxy](../ai-bridge-proxy/index.md) can intercept traffic and forward it to AI Bridge. + ## Base URLs Most AI coding tools allow the "base URL" to be customized. In other words, when a request is made to OpenAI's API from your coding tool, the API endpoint such as [`/v1/chat/completions`](https://platform.openai.com/docs/api-reference/chat) will be appended to the configured base. Therefore, instead of the default base URL of `https://api.openai.com/v1`, you'll need to set it to `https://coder.example.com/api/v2/aibridge/openai/v1`. @@ -55,6 +60,7 @@ The table below shows tested AI clients and their compatibility with AI Bridge. | [VS Code](./vscode.md) | ✅ | ❌ | Only supports Custom Base URL for OpenAI. | | [JetBrains IDEs](./jetbrains.md) | ✅ | ❌ | Works in Chat mode via "Bring Your Own Key". | | [Zed](./zed.md) | ✅ | ✅ | | +| [GitHub Copilot](./copilot.md) | ⚙️ | - | Requires [AI Bridge Proxy](../ai-bridge-proxy/index.md). Uses per-user GitHub tokens. | | WindSurf | ❌ | ❌ | No option to override base URL. | | Cursor | ❌ | ❌ | Override for OpenAI broken ([upstream issue](https://forum.cursor.com/t/requests-are-sent-to-incorrect-endpoint-when-using-base-url-override/144894)). | | Sourcegraph Amp | ❌ | ❌ | No option to override base URL. | @@ -63,7 +69,7 @@ The table below shows tested AI clients and their compatibility with AI Bridge. | Antigravity | ❌ | ❌ | No option to override base URL. | | -*Legend: ✅ supported, ❌ not supported, - not applicable.* +*Legend: ✅ supported, ⚙️ requires AI Bridge Proxy, ❌ not supported, - not applicable.* ## Configuring In-Workspace Tools diff --git a/docs/manifest.json b/docs/manifest.json index 44d322620f..c669a58cfb 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1091,6 +1091,11 @@ "title": "Zed", "description": "Configure Zed to use AI Bridge", "path": "./ai-coder/ai-bridge/clients/zed.md" + }, + { + "title": "GitHub Copilot", + "description": "Configure GitHub Copilot to use AI Bridge via AI Bridge Proxy", + "path": "./ai-coder/ai-bridge/clients/copilot.md" } ] },