How Claude Code's Upstream Proxy Solves Corporate Network Headaches

The Problem: Subprocesses in a Corporate Container

When you run claude code in a cloud container (CCR), every subprocess it spawns—like curl, gh, python, or kubectl—hits a wall. The container sits behind your organization's security perimeter, which needs to inspect traffic, inject API keys, and block unauthorized endpoints. The naive solution is setting HTTPS_PROXY, but this fails because:

1. Certificate Hell: A corporate proxy inspecting HTTPS presents its own MITM certificate. Every tool (curl, Python, Node, Go) has its own CA trust store. Miss one environment variable (CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, etc.) and you get CERTIFICATE_VERIFY_FAILED`.
2. Network Incompatibility: Modern cloud ingress (like GKE L7 load balancers) often uses path-based routing and doesn't support raw HTTP CONNECT tunnels, which HTTPS_PROXY relies on.

The Solution: An Automatic Upstream Proxy Relay

Claude Code solves this with an upstream proxy relay that activates automatically when you're in a cloud container. Here's what it does:

• Runs locally: A TCP server binds to 127.0.0.1:<port> inside your container.
• Tunnels over WebSocket: It accepts standard HTTP CONNECT requests from subprocesses, then tunnels the bytes over WebSocket to the cloud gateway.
• Handles certificates automatically: It provides a CA bundle that trusts both system CAs and your gateway's MITM certificate.
• Is completely transparent: Your subprocesses just see a standard HTTPS proxy. No manual configuration needed.

When It Activates (The Four Gates)

The proxy only turns on when all these conditions are met:

// Simplified activation logic
if (!env.CLAUDE_CODE_REMOTE) return disabled;           // Gate 1: Cloud container?
if (!env.CCR_UPSTREAM_PROXY_ENABLED) return disabled;   // Gate 2: Server enabled it?
if (!env.CLAUDE_CODE_REMOTE_SESSION_ID) return disabled;// Gate 3: Have session ID?
if (!readFile("/run/ccr/session_token")) return disabled;// Gate 4: Token exists?
// All passed → proxy activates

The CCR_UPSTREAM_PROXY_ENABLED flag is evaluated server-side to avoid cold cache issues. Crucially, every step fails open—if anything breaks (CA download fails, relay can't bind), the proxy disables and your session continues normally.

Security: Protecting the Session Token

The most interesting part is the security design against prompt injection attacks. The session token authenticates the relay to your corporate gateway, and Claude Code protects it with a four-step sequence:

1. Read from tmpfs: Token lives in memory-backed storage (/run/ccr/session_token).
2. Block ptrace: Uses Linux's prctl(PR_SET_DUMPABLE, 0) via Bun's FFI to prevent other processes (even same UID) from attaching and scanning memory for the token.
3. Start relay: Only after ptrace is blocked.
4. Unlink token file: The file disappears from the filesystem, though the process retains the handle.

This specifically defends against a malicious prompt tricking Claude into running something like gdb -p $PPID to extract the token from memory.

What This Means For Your Workflow

You don't need to do anything. When you're in a CCR environment, Claude Code automatically:

• Sets HTTP_PROXY and HTTPS_PROXY to the local relay
• Sets NO_PROXY for localhost and internal addresses
• Configures the merged CA bundle via SSL_CERT_FILE
• Handles WebSocket tunneling through your organization's ingress

Your curl https://api.github.com just works. Your pip install just works. Your kubectl commands just work. All while your security team gets the traffic inspection and credential injection they require.

The Bigger Picture: Claude Code's Infrastructure Investment

This isn't just a networking feature—it's a sign of Claude Code maturing as an enterprise tool. The upstream proxy enables Claude Code to operate seamlessly within strict corporate environments where other AI coding tools might struggle with certificate errors or proxy configuration. It follows Anthropic's pattern of building robust infrastructure (like their Model Context Protocol integration) that makes advanced AI capabilities work in real-world scenarios.

For developers, the takeaway is simple: when you're working in a corporate cloud environment with Claude Code, your subprocess HTTP traffic is handled automatically and securely. No more wrestling with certificate bundles or proxy settings—just focus on your code.