feat: configure Copilot CLI offline+BYOK mode when api-proxy is enabled with COPILOT_API_KEY (#1923)

* Initial plan

* feat: support Copilot CLI offline mode + BYOK for api-proxy deployments

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dac02eb8-4902-453e-813b-887f091740f0

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix: accept any unix socket in checkDockerHost

The checkDockerHost function used a Set of two hardcoded socket paths
(/var/run/docker.sock, /run/docker.sock) to validate DOCKER_HOST. Any
other unix socket path (e.g. /tmp/custom-docker.sock) was incorrectly
rejected as an external daemon.

All unix:// sockets are local by definition — only TCP endpoints
(tcp://host:port) indicate an external Docker daemon incompatible
with AWF's network isolation model.

Replace the Set lookup with a unix:// prefix check.

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 Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 4 people

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

@@ -127,6 +127,29 @@ if [ -n "$COPILOT_API_URL" ]; then
     echo "[health-check] ✓ COPILOT_TOKEN is placeholder value (correct)"
   fi
 
+  # Verify COPILOT_PROVIDER_API_KEY (offline+BYOK) is placeholder when api-proxy is enabled (if present)
+  if [ -n "$COPILOT_PROVIDER_API_KEY" ]; then
+    if [ "$COPILOT_PROVIDER_API_KEY" != "placeholder-token-for-credential-isolation" ]; then
+      echo "[health-check][ERROR] COPILOT_PROVIDER_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_PROVIDER_API_KEY is placeholder value (correct)"
+  fi
+
+  # Verify COPILOT_PROVIDER_BASE_URL matches the sidecar URL when set (offline+BYOK mode)
+  if [ -n "$COPILOT_PROVIDER_BASE_URL" ]; then
+    echo "[health-check] COPILOT_PROVIDER_BASE_URL=$COPILOT_PROVIDER_BASE_URL (offline+BYOK mode)"
+    if [ "$COPILOT_PROVIDER_BASE_URL" != "$COPILOT_API_URL" ]; then
+      echo "[health-check][ERROR] COPILOT_PROVIDER_BASE_URL does not match COPILOT_API_URL"
+      echo "[health-check][ERROR] COPILOT_PROVIDER_BASE_URL=$COPILOT_PROVIDER_BASE_URL"
+      echo "[health-check][ERROR] COPILOT_API_URL=$COPILOT_API_URL"
+      exit 1
+    fi
+    echo "[health-check] ✓ COPILOT_PROVIDER_BASE_URL matches COPILOT_API_URL"
+    echo "[health-check] ✓ Copilot CLI offline+BYOK mode configured"
+  fi
+
   # Perform health check using API URL
   echo "[health-check] Testing connectivity to GitHub Copilot API proxy at $COPILOT_API_URL..."
 

docs/api-proxy-sidecar.md

@@ -145,6 +145,9 @@ The agent container receives **redacted placeholders** and proxy URLs:
 | `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 |
+| `COPILOT_OFFLINE` | `true` | `COPILOT_API_KEY` provided to host | Enables offline+BYOK mode (skips GitHub OAuth handshake) |
+| `COPILOT_PROVIDER_BASE_URL` | `http://172.30.0.30:10002` | `COPILOT_API_KEY` provided to host | Points Copilot CLI BYOK provider at sidecar |
+| `COPILOT_PROVIDER_API_KEY` | `placeholder-token-for-credential-isolation` | `COPILOT_API_KEY` provided to host | BYOK provider API key placeholder (real key in sidecar) |
 | `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 |

src/docker-manager.test.ts

@@ -2633,6 +2633,54 @@ describe('docker-manager', () => {
         expect(env.COPILOT_TOKEN).toBe('placeholder-token-for-credential-isolation');
       });
 
+      it('should set COPILOT_OFFLINE=true in agent when copilotApiKey is provided (offline+BYOK mode)', () => {
+        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_OFFLINE).toBe('true');
+      });
+
+      it('should set COPILOT_PROVIDER_BASE_URL in agent when copilotApiKey is provided (offline+BYOK mode)', () => {
+        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_PROVIDER_BASE_URL).toBe('http://172.30.0.30:10002');
+      });
+
+      it('should set COPILOT_PROVIDER_API_KEY placeholder in agent when copilotApiKey is provided (offline+BYOK mode)', () => {
+        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_PROVIDER_API_KEY).toBe('placeholder-token-for-credential-isolation');
+      });
+
+      it('should not set COPILOT_OFFLINE when only copilotGithubToken is provided', () => {
+        const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotGithubToken: 'ghu_test_token' };
+        const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
+        const agent = result.services.agent;
+        const env = agent.environment as Record<string, string>;
+        expect(env.COPILOT_OFFLINE).toBeUndefined();
+      });
+
+      it('should not set COPILOT_PROVIDER_BASE_URL when only copilotGithubToken is provided', () => {
+        const configWithProxy = { ...mockConfig, enableApiProxy: true, copilotGithubToken: 'ghu_test_token' };
+        const result = generateDockerCompose(configWithProxy, mockNetworkConfigWithProxy);
+        const agent = result.services.agent;
+        const env = agent.environment as Record<string, string>;
+        expect(env.COPILOT_PROVIDER_BASE_URL).toBeUndefined();
+      });
+
+      it('should include COPILOT_PROVIDER_API_KEY in AWF_ONE_SHOT_TOKENS', () => {
+        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.AWF_ONE_SHOT_TOKENS).toContain('COPILOT_PROVIDER_API_KEY');
+      });
+
       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);

src/docker-manager.ts

@@ -642,7 +642,7 @@ export function generateDockerCompose(
     }),
     // Configure one-shot-token library with sensitive tokens to protect
     // These tokens are cached on first access and unset from /proc/self/environ
-    AWF_ONE_SHOT_TOKENS: 'COPILOT_GITHUB_TOKEN,GITHUB_TOKEN,GH_TOKEN,GITHUB_API_TOKEN,GITHUB_PAT,GH_ACCESS_TOKEN,OPENAI_API_KEY,OPENAI_KEY,ANTHROPIC_API_KEY,CLAUDE_API_KEY,CODEX_API_KEY,COPILOT_API_KEY',
+    AWF_ONE_SHOT_TOKENS: 'COPILOT_GITHUB_TOKEN,GITHUB_TOKEN,GH_TOKEN,GITHUB_API_TOKEN,GITHUB_PAT,GH_ACCESS_TOKEN,OPENAI_API_KEY,OPENAI_KEY,ANTHROPIC_API_KEY,CLAUDE_API_KEY,CODEX_API_KEY,COPILOT_API_KEY,COPILOT_PROVIDER_API_KEY',
   };
 
   // When api-proxy is enabled with Copilot, set placeholder tokens early
@@ -654,6 +654,8 @@ export function generateDockerCompose(
   if (config.enableApiProxy && config.copilotApiKey) {
     environment.COPILOT_API_KEY = 'placeholder-token-for-credential-isolation';
     logger.debug('COPILOT_API_KEY set to placeholder value (early) to prevent --env-all override');
+    environment.COPILOT_PROVIDER_API_KEY = 'placeholder-token-for-credential-isolation';
+    logger.debug('COPILOT_PROVIDER_API_KEY set to placeholder value (early) to prevent --env-all override');
   }
 
   // Always set NO_PROXY to prevent HTTP clients from proxying localhost traffic through Squid.
@@ -1636,6 +1638,22 @@ export function generateDockerCompose(
       // Note: COPILOT_GITHUB_TOKEN and COPILOT_API_KEY placeholders are set early (before --env-all)
       // to prevent override by host environment variable
     }
+    if (config.copilotApiKey) {
+      // Enable Copilot CLI offline + BYOK mode so it skips the GitHub OAuth handshake
+      // and talks directly to the sidecar without needing GitHub authentication for inference.
+      // Reference: https://github.blog/changelog/2026-04-07-copilot-cli-now-supports-byok-and-local-models/
+      environment.COPILOT_OFFLINE = 'true';
+      logger.debug('COPILOT_OFFLINE set to true for offline+BYOK mode');
+
+      // Point Copilot CLI's BYOK provider URL at the sidecar, which injects the real API key
+      // and forwards the request through Squid. This is the new canonical BYOK env var.
+      environment.COPILOT_PROVIDER_BASE_URL = `http://${networkConfig.proxyIp}:${API_PROXY_PORTS.COPILOT}`;
+      logger.debug(`COPILOT_PROVIDER_BASE_URL set to sidecar at http://${networkConfig.proxyIp}:${API_PROXY_PORTS.COPILOT}`);
+
+      // COPILOT_PROVIDER_API_KEY placeholder: real key is held by the sidecar, never exposed to agent.
+      // Set early placeholder (before this block) already handled above.
+      logger.debug('COPILOT_PROVIDER_API_KEY placeholder set for credential isolation');
+    }
     if (config.geminiApiKey) {
       environment.GEMINI_API_BASE_URL = `http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`;
       logger.debug(`Google Gemini API will be proxied through sidecar at http://${networkConfig.proxyIp}:${API_PROXY_PORTS.GEMINI}`);