6.8 KiB
Claude Code agent proxy
Outbound HTTPS from this session goes through a local proxy at ${AGENT_PROXY_URL} (set via HTTPS_PROXY) which tunnels to a policy-enforcing egress proxy. TLS is re-terminated there, so every tool must trust the CA bundle at ${AGENT_PROXY_CA_BUNDLE_PATH}. The standard CA environment variables, the system trust store (where possible), a JVM truststore, the Bazel system bazelrc, the browser NSS store, and gsutil's boto config are already set up.
Quick diagnosis
- Run: curl -sS ${AGENT_PROXY_URL}/__agentproxy/status It reports proxy state, which trust and git accommodations are active (javaTrustStorePath, toolTrustFailureCodes, gitSshRewrite, gitConfigConflicts), and the most recent proxy-side failures.
- Find the failure class below and apply the matching fix; gitConfigConflicts codes map to the git section, toolTrustFailureCodes to the JVM section.
- Never disable TLS verification, never unset HTTPS_PROXY, and do not retry policy denials (403/407) — report them instead.
Failure classes and fixes
"certificate verify failed" / "self-signed certificate in chain" / PKIX errors
The failing tool is not reading the pre-set CA configuration. In order:
- If the tool has a CA flag or env var, point it at ${AGENT_PROXY_CA_BUNDLE_PATH} (examples: --cacert, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, AWS_CA_BUNDLE, DENO_CERT, CARGO_HTTP_CAINFO, PIP_CERT, GIT_SSL_CAINFO, BUNDLE_SSL_CA_CERT, HEX_CACERTS_PATH, NIX_SSL_CERT_FILE).
- Tool config files override environment variables. If one of these sets its own CA or disables verification, point it at the bundle instead: pip.conf "cert", npm "cafile" (npm config get cafile), ~/.curlrc "cacert", .wgetrc "ca_certificate", conda "ssl_verify", git "http.sslCAInfo", gradle.properties / MAVEN_OPTS "-Djavax.net.ssl.trustStore".
- JVM tools (Maven, Gradle, plain Java): when a JDK is present, JAVA_TOOL_OPTIONS points JVMs at a truststore that holds the proxy CA: the JDK's own store if the system trust install already added the CA there, otherwise ${AGENT_PROXY_STATE_DIR}/java-truststore.p12 (password "changeit"). Confirm javaTrustStorePath is set in the status output before pointing a build at it (toolTrustFailureCodes explains why it is missing). If the image or the build sets its own trustStore, that one wins — import the proxy CA into it with keytool -importcert -noprompt -alias ccr-agent-proxy -file ${AGENT_PROXY_STATE_DIR}/agent-proxy-ca.crt -keystore or point the build at the ready-made one. Bazel reads the managed block in /etc/bazel.bazelrc rather than JAVA_TOOL_OPTIONS.
"405 Method Not Allowed" from the proxy
The tool sent a plain-HTTP (non-CONNECT) request: usually axios older than 1.16.1 (upgrade it) or a tool configured with HTTP_PROXY (unset HTTP_PROXY for that tool — only HTTPS_PROXY is supported).
403 / 407 from the proxy
Most often the destination host is not allowed for this session. Do not retry or route around it — report the blocked host. Note: curl hides response bodies on failed CONNECTs; the status endpoint records the reason.
429 / 503 from the proxy
Too many connections or requests went through the proxy, or the egress proxy was busy. The proxy can hold a connection for about a minute before it refuses it, so a tool with a short timeout of its own may report only a timeout. Run fewer downloads or requests at once, then retry. connectsWaitingForTunnel and openTunnels in the status output show the load. busyTunnels includes idle connections until one has to wait, so alone it does not show load, and it can pass maxBusyTunnels. busyTunnelsKeptForClaudeCode is the same count for connections of Claude Code itself that had to wait and took a tunnel kept for them. Those have a limit of their own, on top of maxBusyTunnels, and openTunnels includes them, so openTunnels can pass maxOpenTunnels.
The proxy also answers 429 immediately when too many connections to it are open, idle ones included (too_many_connections in the [agent-proxy] lines under a failed command). Look for a program that opens connections and never closes them. New connections work again once some have closed.
408 from the proxy
The tool opened a connection to the proxy and sent no complete request within 30 seconds, so the proxy closed it. Retry once. If it happens again, the tool opens connections before it has a request to send, it is paused or short of CPU, or its request never ends with an empty line in CRLF form (bare LF line ends, or another protocol such as SOCKS).
"connection reset" / "unexpected disconnect" / "RPC failed" mid-transfer
Once a tunnel is up the proxy cannot send an error response, so a connection it aborts (tunnel to the egress proxy lost, or an upload the tunnel stopped accepting) reaches the tool as a bare reset. recentRelayFailures in the status output names the host and reason; check it before concluding the remote service refused the operation.
Tool ignores the proxy entirely (timeouts with no proxy error)
Some clients do not read HTTPS_PROXY: Node's built-in fetch (run that command with NODE_USE_ENV_PROXY=1 on Node >= 22.21), aiohttp (pass trust_env=True), Ruby bundler (reads only HTTP_PROXY, which this proxy does not serve), hand-rolled Go dialers. Prefer the tool's own proxy option where one exists.
git
SSH-form GitHub remotes (git@github.com:...) are rewritten to HTTPS automatically unless this session has its own SSH setup or supplies its own GIT_CONFIG_* (see gitSshRewrite in the status output). A gitconfig that sets http.proxy / http..proxy (even empty), its own http.sslCAInfo, or an https-to-ssh insteadOf makes git bypass the proxy or fail verification — the status output's gitConfigConflicts codes name which of these were detected; adjust those keys for this session if git times out.
docker build / docker run
Processes inside containers cannot reach 127.0.0.1:${AGENT_PROXY_PORT} and do not trust the CA. Workarounds: run builds with --network host, copy ${AGENT_PROXY_CA_BUNDLE_PATH} into the build context and install it in an early layer, and pass proxy/CA settings explicitly to the build.
Not supported through the proxy (report, do not work around)
gRPC / HTTP/2-only APIs, WebSocket upgrades, client-mTLS, certificate-pinned clients (e.g. Snowflake, ngrok), non-443 HTTPS ports, raw-TCP databases.
If a tool still cannot work through the proxy, report it so the policy or tooling can be fixed.