CLI proxy: start difc-proxy on host, pass --difc-proxy-host to AWF

[lpcox]

Summary

AWF is redesigning its CLI proxy feature to not manage the mcpg DIFC proxy container internally. Instead, the gh-aw compiler should start the difc-proxy on the host before the AWF step, and pass the connection details to AWF via new CLI flags.

Background

When features: cli-proxy: true is set, the compiler currently emits --enable-cli-proxy on the AWF command. AWF then internally starts an awf-cli-proxy-mcpg container (using ghcr.io/github/gh-aw-mcpg) inside its Docker Compose network.

This approach has proven unreliable because AWF runs mcpg with:

• cap_drop: ALL, no-new-privileges, pids_limit: 50, mem_limit: 256m
• HTTP/HTTPS traffic routed through Squid proxy
• Isolated Docker network (not --network host)
• run.sh → run_containerized.sh entrypoint redirection issues

mcpg consistently crashes with exit code 1 in this environment. In contrast, gh-aw already runs mcpg successfully on the host via start_difc_proxy.sh with --network host and no restrictions.

Requested Change

1. Start difc-proxy on the host before AWF

When features: cli-proxy: true, add a workflow step (before the AWF execution step) that starts the difc-proxy on the host, similar to how start_difc_proxy.sh works. The difc-proxy should:

• Run with --network host (as it does today)
• Listen on 0.0.0.0:18443 (or a configurable port)
• Use --tls with certs written to a known directory (e.g., /tmp/gh-aw/difc-proxy-tls/)
• Have the guard policy set by the compiler (the allow-only wrapper format)
• Receive GH_TOKEN for upstream API authentication

2. Replace --enable-cli-proxy with new AWF flags

The AWF command should use these new flags instead of --enable-cli-proxy:

sudo -E awf \
  --difc-proxy-host host.docker.internal:18443 \
  --difc-proxy-ca-cert /tmp/gh-aw/difc-proxy-tls/ca.crt \
  ... other flags ...

--difc-proxy-host <host:port> — Tells AWF where the external difc-proxy is running. Its presence enables the cli-proxy sidecar. Replaces --enable-cli-proxy.

--difc-proxy-ca-cert <path> — Path to the TLS CA cert written by the difc-proxy. AWF mounts this into the cli-proxy container so gh CLI can trust the self-signed cert.

3. Remove flags that AWF no longer needs

These flags are being removed from AWF (the compiler should stop emitting them if it does):

• --enable-cli-proxy (replaced by --difc-proxy-host)
• --cli-proxy-policy (compiler handles policy directly)
• --cli-proxy-mcpg-image (compiler handles mcpg image)

4. Inject GH_TOKEN into AWF step env

The AWF step needs GH_TOKEN in its environment (with --exclude-env GH_TOKEN to prevent it from reaching the agent). Currently the compiler adds --enable-cli-proxy but does not inject the token — AWF reads it from process.env.GH_TOKEN.

- name: Execute agent
  env:
    GH_TOKEN: ${{ secrets.GH_AW_GITHUB_TOKEN || github.token }}
  run: |
    sudo -E awf \
      --difc-proxy-host host.docker.internal:18443 \
      --difc-proxy-ca-cert /tmp/gh-aw/difc-proxy-tls/ca.crt \
      --exclude-env GH_TOKEN \
      ...

Architecture (after change)

Host (managed by gh-aw compiler):
  difc-proxy (mcpg in proxy mode) on 0.0.0.0:18443, --network host

AWF docker-compose:
  squid-proxy (172.30.0.10)
  cli-proxy (172.30.0.50) → host difc-proxy via host.docker.internal:18443
  agent (172.30.0.20) → cli-proxy at http://172.30.0.50:11000

• cli-proxy (Node.js + gh CLI): runs a TCP tunnel from localhost:18443 → host.docker.internal:18443 so that GH_HOST=localhost:18443 matches the difc-proxy TLS cert SANs (localhost, 127.0.0.1).
• Agent calls cli-proxy at http://172.30.0.50:11000/exec via the gh wrapper script (unchanged).

AWF PR

The corresponding AWF changes will be in a PR in github/gh-aw-firewall that:

• Adds --difc-proxy-host and --difc-proxy-ca-cert flags
• Removes --enable-cli-proxy, --cli-proxy-policy, --cli-proxy-mcpg-image
• Removes the internal mcpg container from docker-compose
• Gives cli-proxy its own IP (172.30.0.50) on the AWF network
• Adds a Node.js TCP tunnel (tcp-tunnel.js) in the cli-proxy container
• Mounts the host CA cert into the cli-proxy container

Related

• gh-aw-firewall PR [tidy] Recompile workflows with updated formatting #1778 (merged): original cli-proxy mcpg container split
• gh-aw-firewall PR [WIP] Fix documentation bloat in tools reference #1801 (closed): smoke-copilot cli-proxy integration — mcpg container crashes
• gh-aw PR feat: add cli-proxy feature flag for AWF gh CLI proxy sidecar (firewall v0.25.14) #24997: added features: cli-proxy to compiler frontmatter