feat: add Copilot BYOK support via COPILOT_API_KEY (#1918)

* Initial plan

* feat: add Copilot BYOK support via COPILOT_API_KEY env var

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/048378d6-92ce-40bd-bf1b-e668cf5ceb38

* test: improve warning message assertion for COPILOT_API_KEY

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/048378d6-92ce-40bd-bf1b-e668cf5ceb38

* fix: address review feedback on BYOK support

- Reword docker-manager comment to clarify placeholder behavior
  when api-proxy is enabled
- Update github-copilot example to accept either COPILOT_GITHUB_TOKEN
  or COPILOT_API_KEY instead of hard-requiring COPILOT_API_KEY
- Extract resolveCopilotAuthToken() as a testable function with
  JSDoc and export it from server.js
- Add 8 unit tests covering precedence, fallback, empty/whitespace
  handling, and trimming behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Landon Cox <landon.cox@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

containers/agent/api-proxy-health-check.sh

@@ -107,6 +107,16 @@ if [ -n "$COPILOT_API_URL" ]; then
     echo "[health-check] ✓ COPILOT_GITHUB_TOKEN is placeholder value (correct)"
   fi
 
+  # Verify COPILOT_API_KEY (BYOK) is placeholder when api-proxy is enabled (if present)
+  if [ -n "$COPILOT_API_KEY" ]; then
+    if [ "$COPILOT_API_KEY" != "placeholder-token-for-credential-isolation" ]; then
+      echo "[health-check][ERROR] COPILOT_API_KEY contains non-placeholder value!"
+      echo "[health-check][ERROR] Token should be 'placeholder-token-for-credential-isolation'"
+      exit 1
+    fi
+    echo "[health-check] ✓ COPILOT_API_KEY is placeholder value (correct)"
+  fi
+
   # Verify COPILOT_TOKEN is placeholder (if present)
   if [ -n "$COPILOT_TOKEN" ]; then
     if [ "$COPILOT_TOKEN" != "placeholder-token-for-credential-isolation" ]; then

containers/api-proxy/server.js

@@ -62,6 +62,21 @@ function shouldStripHeader(name) {
 const OPENAI_API_KEY = (process.env.OPENAI_API_KEY || '').trim() || undefined;
 const ANTHROPIC_API_KEY = (process.env.ANTHROPIC_API_KEY || '').trim() || undefined;
 const COPILOT_GITHUB_TOKEN = (process.env.COPILOT_GITHUB_TOKEN || '').trim() || undefined;
+const COPILOT_API_KEY = (process.env.COPILOT_API_KEY || '').trim() || undefined;
+
+/**
+ * Resolves the Copilot auth token from environment variables.
+ * COPILOT_GITHUB_TOKEN (GitHub OAuth) takes precedence over COPILOT_API_KEY (direct key).
+ * @param {Record<string, string|undefined>} env - Environment variables to inspect
+ * @returns {string|undefined} The resolved auth token, or undefined if neither is set
+ */
+function resolveCopilotAuthToken(env = process.env) {
+  const githubToken = (env.COPILOT_GITHUB_TOKEN || '').trim() || undefined;
+  const apiKey = (env.COPILOT_API_KEY || '').trim() || undefined;
+  return githubToken || apiKey;
+}
+
+const COPILOT_AUTH_TOKEN = resolveCopilotAuthToken(process.env);
 const GEMINI_API_KEY = (process.env.GEMINI_API_KEY || '').trim() || undefined;
 
 /**
@@ -213,7 +228,9 @@ logRequest('info', 'startup', {
     openai: !!OPENAI_API_KEY,
     anthropic: !!ANTHROPIC_API_KEY,
     gemini: !!GEMINI_API_KEY,
-    copilot: !!COPILOT_GITHUB_TOKEN,
+    copilot: !!COPILOT_AUTH_TOKEN,
+    copilot_github_token: !!COPILOT_GITHUB_TOKEN,
+    copilot_api_key: !!COPILOT_API_KEY,
   },
 });
 
@@ -752,7 +769,7 @@ function healthResponse() {
       openai: !!OPENAI_API_KEY,
       anthropic: !!ANTHROPIC_API_KEY,
       gemini: !!GEMINI_API_KEY,
-      copilot: !!COPILOT_GITHUB_TOKEN,
+      copilot: !!COPILOT_AUTH_TOKEN,
     },
     metrics_summary: metrics.getSummary(),
     rate_limits: limiter.getAllStatus(),
@@ -857,7 +874,9 @@ if (require.main === module) {
 
 
   // GitHub Copilot API proxy (port 10002)
-  if (COPILOT_GITHUB_TOKEN) {
+  // Supports COPILOT_GITHUB_TOKEN (GitHub OAuth) and COPILOT_API_KEY (BYOK direct key).
+  // COPILOT_GITHUB_TOKEN takes precedence when both are set.
+  if (COPILOT_AUTH_TOKEN) {
     const copilotServer = http.createServer((req, res) => {
       // Health check endpoint
       if (req.url === '/health' && req.method === 'GET') {
@@ -870,13 +889,13 @@ if (require.main === module) {
       if (checkRateLimit(req, res, 'copilot', contentLength)) return;
 
       proxyRequest(req, res, COPILOT_API_TARGET, {
-        'Authorization': `Bearer ${COPILOT_GITHUB_TOKEN}`,
+        'Authorization': `Bearer ${COPILOT_AUTH_TOKEN}`,
       }, 'copilot');
     });
 
     copilotServer.on('upgrade', (req, socket, head) => {
       proxyWebSocket(req, socket, head, COPILOT_API_TARGET, {
-        'Authorization': `Bearer ${COPILOT_GITHUB_TOKEN}`,
+        'Authorization': `Bearer ${COPILOT_AUTH_TOKEN}`,
       }, 'copilot');
     });
 
@@ -992,4 +1011,4 @@ if (require.main === module) {
 }
 
 // Export for testing
-module.exports = { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket };
+module.exports = { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket, resolveCopilotAuthToken };

containers/api-proxy/server.test.js

@@ -5,7 +5,7 @@
 const http = require('http');
 const tls = require('tls');
 const { EventEmitter } = require('events');
-const { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket } = require('./server');
+const { normalizeApiTarget, deriveCopilotApiTarget, normalizeBasePath, buildUpstreamPath, proxyWebSocket, resolveCopilotAuthToken } = require('./server');
 
 describe('normalizeApiTarget', () => {
   it('should strip https:// prefix', () => {
@@ -620,3 +620,43 @@ describe('proxyWebSocket', () => {
   });
 });
 
+describe('resolveCopilotAuthToken', () => {
+  it('should return COPILOT_GITHUB_TOKEN when only it is set', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: 'gho_abc123' })).toBe('gho_abc123');
+  });
+
+  it('should return COPILOT_API_KEY when only it is set', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_API_KEY: 'sk-byok-key' })).toBe('sk-byok-key');
+  });
+
+  it('should prefer COPILOT_GITHUB_TOKEN over COPILOT_API_KEY when both are set', () => {
+    expect(resolveCopilotAuthToken({
+      COPILOT_GITHUB_TOKEN: 'gho_abc123',
+      COPILOT_API_KEY: 'sk-byok-key',
+    })).toBe('gho_abc123');
+  });
+
+  it('should return undefined when neither is set', () => {
+    expect(resolveCopilotAuthToken({})).toBeUndefined();
+  });
+
+  it('should return undefined for empty strings', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: '', COPILOT_API_KEY: '' })).toBeUndefined();
+  });
+
+  it('should return undefined for whitespace-only values', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_GITHUB_TOKEN: '  ', COPILOT_API_KEY: '  \n' })).toBeUndefined();
+  });
+
+  it('should trim whitespace from token values', () => {
+    expect(resolveCopilotAuthToken({ COPILOT_API_KEY: '  sk-byok-key  ' })).toBe('sk-byok-key');
+  });
+
+  it('should fall back to COPILOT_API_KEY when COPILOT_GITHUB_TOKEN is whitespace-only', () => {
+    expect(resolveCopilotAuthToken({
+      COPILOT_GITHUB_TOKEN: '  ',
+      COPILOT_API_KEY: 'sk-byok-key',
+    })).toBe('sk-byok-key');
+  });
+});
+

docs-site/src/content/docs/reference/cli-reference.md

@@ -675,6 +675,7 @@ sudo -E awf --enable-api-proxy \
 | `OPENAI_API_KEY` | OpenAI / Codex |
 | `ANTHROPIC_API_KEY` | Anthropic / Claude |
 | `COPILOT_GITHUB_TOKEN` | GitHub Copilot |
+| `COPILOT_API_KEY` | GitHub Copilot (BYOK) |
 
 **Sidecar ports:**
 

docs/api-proxy-sidecar.md

@@ -123,6 +123,7 @@ The API proxy sidecar receives **real credentials** and routing configuration:
 | `OPENAI_API_KEY` | Real API key | `--enable-api-proxy` and env set | OpenAI API key (injected into requests) |
 | `ANTHROPIC_API_KEY` | Real API key | `--enable-api-proxy` and env set | Anthropic API key (injected into requests) |
 | `COPILOT_GITHUB_TOKEN` | Real token | `--enable-api-proxy` and env set | GitHub Copilot token (injected into requests) |
+| `COPILOT_API_KEY` | Real API key | `--enable-api-proxy` and env set | GitHub Copilot BYOK key (injected into requests) |
 | `HTTP_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid for domain filtering |
 | `HTTPS_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid for domain filtering |
 
@@ -140,9 +141,10 @@ The agent container receives **redacted placeholders** and proxy URLs:
 | `ANTHROPIC_BASE_URL` | `http://172.30.0.30:10001` | `ANTHROPIC_API_KEY` provided to host | Redirects Anthropic SDK to proxy |
 | `ANTHROPIC_AUTH_TOKEN` | `placeholder-token-for-credential-isolation` | `ANTHROPIC_API_KEY` provided to host | Placeholder token (real auth via BASE_URL) |
 | `CLAUDE_CODE_API_KEY_HELPER` | `/usr/local/bin/get-claude-key.sh` | `ANTHROPIC_API_KEY` provided to host | Helper script for Claude Code CLI |
-| `COPILOT_API_URL` | `http://172.30.0.30:10002` | `COPILOT_GITHUB_TOKEN` provided to host | Redirects Copilot CLI to proxy |
-| `COPILOT_TOKEN` | `placeholder-token-for-credential-isolation` | `COPILOT_GITHUB_TOKEN` provided to host | Placeholder token (real auth via API_URL) |
+| `COPILOT_API_URL` | `http://172.30.0.30:10002` | `COPILOT_GITHUB_TOKEN` or `COPILOT_API_KEY` provided to host | Redirects Copilot CLI to proxy |
+| `COPILOT_TOKEN` | `placeholder-token-for-credential-isolation` | `COPILOT_GITHUB_TOKEN` or `COPILOT_API_KEY` provided to host | Placeholder token (real auth via API_URL) |
 | `COPILOT_GITHUB_TOKEN` | `placeholder-token-for-credential-isolation` | `COPILOT_GITHUB_TOKEN` provided to host | Placeholder token protected by one-shot-token |
+| `COPILOT_API_KEY` | `placeholder-token-for-credential-isolation` | `COPILOT_API_KEY` provided to host | BYOK placeholder token protected by one-shot-token |
 | `OPENAI_API_KEY` | Not set | `--enable-api-proxy` | Excluded from agent (held in api-proxy) |
 | `ANTHROPIC_API_KEY` | Not set | `--enable-api-proxy` | Excluded from agent (held in api-proxy) |
 | `HTTP_PROXY` | `http://172.30.0.10:3128` | Always | Routes through Squid proxy |

examples/github-copilot.sh

@@ -6,7 +6,7 @@
 #
 # Prerequisites:
 # - GitHub Copilot CLI installed: npm install -g @github/copilot
-# - COPILOT_API_KEY environment variable set (for API proxy)
+# - COPILOT_GITHUB_TOKEN or COPILOT_API_KEY environment variable set (for API proxy)
 # - GITHUB_TOKEN environment variable set (for GitHub API access)
 #
 # Usage: sudo -E ./examples/github-copilot.sh
@@ -16,10 +16,12 @@ set -e
 echo "=== AWF GitHub Copilot CLI Example (with API Proxy) ==="
 echo ""
 
-# Check for COPILOT_API_KEY
-if [ -z "$COPILOT_API_KEY" ]; then
-  echo "Error: COPILOT_API_KEY environment variable is not set"
-  echo "Set it with: export COPILOT_API_KEY='your_copilot_api_key'"
+# Check for Copilot credential (COPILOT_GITHUB_TOKEN or COPILOT_API_KEY)
+if [ -z "$COPILOT_GITHUB_TOKEN" ] && [ -z "$COPILOT_API_KEY" ]; then
+  echo "Error: No Copilot credential set"
+  echo "Set one of:"
+  echo "  export COPILOT_GITHUB_TOKEN='your_github_token'"
+  echo "  export COPILOT_API_KEY='your_copilot_api_key'"
   exit 1
 fi
 
@@ -37,7 +39,8 @@ echo "Running GitHub Copilot CLI with API proxy and debug logging enabled..."
 echo ""
 
 # Run Copilot CLI with API proxy enabled
-# Use sudo -E to preserve environment variables (COPILOT_GITHUB_TOKEN, GITHUB_TOKEN, AWF_ONE_SHOT_TOKEN_DEBUG)
+# Use sudo -E to preserve environment variables (COPILOT_GITHUB_TOKEN, COPILOT_API_KEY, GITHUB_TOKEN, AWF_ONE_SHOT_TOKEN_DEBUG)
+# The api-proxy sidecar holds the real Copilot credential and injects it into requests.
 # Required domains:
 # - api.githubcopilot.com: Copilot API endpoint (proxied via api-proxy)
 # - github.com: GitHub API access

src/cli.test.ts

@@ -1397,6 +1397,10 @@ describe('cli', () => {
       expect(result.enabled).toBe(true);
       expect(result.warnings).toHaveLength(2);
       expect(result.warnings[0]).toContain('no API keys found');
+      expect(result.warnings[1]).toContain('OPENAI_API_KEY');
+      expect(result.warnings[1]).toContain('ANTHROPIC_API_KEY');
+      expect(result.warnings[1]).toContain('COPILOT_GITHUB_TOKEN');
+      expect(result.warnings[1]).toContain('COPILOT_API_KEY');
       expect(result.warnings[1]).toContain('GEMINI_API_KEY');
       expect(result.debugMessages).toEqual([]);
     });

src/cli.ts

@@ -297,7 +297,7 @@ export function validateApiProxyConfig(
 
   if (!hasOpenaiKey && !hasAnthropicKey && !hasCopilotKey && !hasGeminiKey) {
     warnings.push('⚠️  API proxy enabled but no API keys found in environment');
-    warnings.push('   Set OPENAI_API_KEY, ANTHROPIC_API_KEY, COPILOT_GITHUB_TOKEN, or GEMINI_API_KEY to use the proxy');
+    warnings.push('   Set OPENAI_API_KEY, ANTHROPIC_API_KEY, COPILOT_GITHUB_TOKEN, COPILOT_API_KEY, or GEMINI_API_KEY to use the proxy');
   }
   if (hasOpenaiKey) {
     debugMessages.push('OpenAI API key detected - will be held securely in sidecar');
@@ -1903,6 +1903,7 @@ program
       openaiApiKey: process.env.OPENAI_API_KEY,
       anthropicApiKey: process.env.ANTHROPIC_API_KEY,
       copilotGithubToken: process.env.COPILOT_GITHUB_TOKEN,
+      copilotApiKey: process.env.COPILOT_API_KEY,
       geminiApiKey: process.env.GEMINI_API_KEY,
       copilotApiTarget: options.copilotApiTarget || process.env.COPILOT_API_TARGET,
       openaiApiTarget: options.openaiApiTarget || process.env.OPENAI_API_TARGET,
@@ -1993,13 +1994,13 @@ program
       config.enableApiProxy || false,
       !!config.openaiApiKey,
       !!config.anthropicApiKey,
-      !!config.copilotGithubToken,
+      !!(config.copilotGithubToken || config.copilotApiKey),
       !!config.geminiApiKey
     );
 
     // Log API proxy status at info level for visibility
     if (config.enableApiProxy) {
-      logger.info(`API proxy enabled: OpenAI=${!!config.openaiApiKey}, Anthropic=${!!config.anthropicApiKey}, Copilot=${!!config.copilotGithubToken}, Gemini=${!!config.geminiApiKey}`);
+      logger.info(`API proxy enabled: OpenAI=${!!config.openaiApiKey}, Anthropic=${!!config.anthropicApiKey}, Copilot=${!!(config.copilotGithubToken || config.copilotApiKey)}, Gemini=${!!config.geminiApiKey}`);
     }
 
     for (const warning of apiProxyValidation.warnings) {
@@ -2052,7 +2053,7 @@ program
     // to prevent sensitive data from flowing to logger (CodeQL sensitive data logging)
     const redactedConfig: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(config)) {
-      if (key === 'openaiApiKey' || key === 'anthropicApiKey' || key === 'copilotGithubToken' || key === 'geminiApiKey') continue;
+      if (key === 'openaiApiKey' || key === 'anthropicApiKey' || key === 'copilotGithubToken' || key === 'copilotApiKey' || key === 'geminiApiKey') continue;
       redactedConfig[key] = key === 'agentCommand' ? redactSecrets(value as string) : value;
     }
     logger.debug('Configuration:', JSON.stringify(redactedConfig, null, 2));

src/docker-manager.test.ts

@@ -722,6 +722,26 @@ describe('docker-manager', () => {
       delete process.env.COPILOT_GITHUB_TOKEN;
     });
 
+    it('should forward COPILOT_API_KEY when api-proxy is disabled', () => {
+      process.env.COPILOT_API_KEY = 'cpat_test_byok_key';
+      const configNoProxy = { ...mockConfig, enableApiProxy: false };
+      const result = generateDockerCompose(configNoProxy, mockNetworkConfig);
+      const env = result.services.agent.environment as Record<string, string>;
+      expect(env.COPILOT_API_KEY).toBe('cpat_test_byok_key');
+      delete process.env.COPILOT_API_KEY;
+    });
+
+    it('should not forward COPILOT_API_KEY to agent when api-proxy is enabled', () => {
+      process.env.COPILOT_API_KEY = 'cpat_test_byok_key';
+      const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotApiKey: 'cpat_test_byok_key' };
+      const proxyNetworkConfig = { ...mockNetworkConfig, proxyIp: '172.30.0.30' };
+      const result = generateDockerCompose(configWithProxy, proxyNetworkConfig);
+      const env = result.services.agent.environment as Record<string, string>;
+      // Placeholder is set to prevent --env-all from leaking the real key
+      expect(env.COPILOT_API_KEY).toBe('placeholder-token-for-credential-isolation');
+      delete process.env.COPILOT_API_KEY;
+    });
+
     it('should forward AWF_ONE_SHOT_TOKEN_DEBUG when set', () => {
       process.env.AWF_ONE_SHOT_TOKEN_DEBUG = '1';
       const result = generateDockerCompose(mockConfig, mockNetworkConfig);
@@ -2589,6 +2609,30 @@ describe('docker-manager', () => {
         expect(env.COPILOT_API_TARGET).toBeUndefined();
       });
 
+      it('should pass COPILOT_API_KEY to api-proxy env when copilotApiKey is provided', () => {
+        const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotApiKey: 'cpat_test_byok_key' };
+        const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
+        const proxy = result.services['api-proxy'];
+        const env = proxy.environment as Record<string, string>;
+        expect(env.COPILOT_API_KEY).toBe('cpat_test_byok_key');
+      });
+
+      it('should set COPILOT_API_URL in agent when only copilotApiKey is provided', () => {
+        const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotApiKey: 'cpat_test_byok_key' };
+        const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
+        const agent = result.services.agent;
+        const env = agent.environment as Record<string, string>;
+        expect(env.COPILOT_API_URL).toBe('http://172.30.0.30:10002');
+      });
+
+      it('should set COPILOT_TOKEN placeholder when copilotApiKey is provided', () => {
+        const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotApiKey: 'cpat_test_byok_key' };
+        const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
+        const agent = result.services.agent;
+        const env = agent.environment as Record<string, string>;
+        expect(env.COPILOT_TOKEN).toBe('placeholder-token-for-credential-isolation');
+      });
+
       it('should include api-proxy service when enableApiProxy is true with Gemini key', () => {
         const configWithProxy = { ...mockConfig, enableApiProxy: true, geminiApiKey: 'AIza-test-gemini-key' };
         const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);