Upstream Proxy System

Claude Code Remote (CCR) runs inside sandboxed GKE containers. Enterprise customers need outbound HTTP traffic — curl, GitHub CLI, npm install, Datadog agents — to carry injected credentials (e.g. DD-API-KEY) and to be auditable. The solution is an HTTPS CONNECT proxy running locally on 127.0.0.1 inside each container, tunnelled back to Anthropic's gateway over a WebSocket. The gateway MITMs TLS, injects org-configured headers, and forwards to the real upstream.

initUpstreamProxy() is called exactly once from init.ts at startup. It runs six steps, each conditional on the previous succeeding:

The relay is a local TCP server. Clients (curl, gh, kubectl) connect and send standard HTTP CONNECT host:port requests. The relay upgrades a WebSocket to Anthropic's gateway and tunnels bytes bidirectionally.

Two-Phase Connection Handling

The handleData() function implements a clean two-phase state machine per TCP connection:

// Phase 1: accumulate until CRLF CRLF terminates the CONNECT header
if (!st.ws) {
  st.connectBuf = Buffer.concat([st.connectBuf, data])
  const headerEnd = st.connectBuf.indexOf('\r\n\r\n')
  if (headerEnd === -1) { /* guard: reject if > 8192 bytes */ return }
  // parse CONNECT host:port, stash trailing bytes, open WS tunnel
  openTunnel(sock, st, firstLine, wsUrl, authHeader, wsAuthHeader)
  return
}
// Phase 2: pump bytes to WebSocket (buffer if WS not open yet)
if (!st.wsOpen) { st.pending.push(Buffer.from(data)); return }
forwardToWs(st.ws, data)

Bytes crossing the WebSocket are wrapped in an UpstreamProxyChunk protobuf message. Rather than pulling in protobufjs for a single one-field message, the code encodes and decodes by hand:

// message UpstreamProxyChunk { bytes data = 1; }
// tag = (field 1 << 3) | wire_type 2 (length-delimited) = 0x0a
export function encodeChunk(data: Uint8Array): Uint8Array {
  const len = data.length
  const varint: number[] = []
  let n = len
  while (n > 0x7f) { varint.push((n & 0x7f) | 0x80); n >>>= 7 }
  varint.push(n)
  const out = new Uint8Array(1 + varint.length + len)
  out[0] = 0x0a
  out.set(varint, 1)
  out.set(data, 1 + varint.length)
  return out
}

The tag byte is always 0x0a. The length is a standard protobuf varint — 7 bits per byte, MSB set on continuation bytes. decodeChunk validates both the tag and that the declared length fits within the buffer, returning null for malformed frames and new Uint8Array(0) for zero-length keepalive chunks.

startUpstreamProxyRelay() dispatches at runtime: if typeof Bun !== 'undefined' it calls startBunRelay; otherwise startNodeRelay. CCR containers run Claude Code under Node, not Bun, so startNodeRelay is the production path. startBunRelay is used in developer environments and must be tested explicitly.

Key difference: write backpressure

Node's net.Socket.write() always buffers — a false return signals backpressure but no bytes are lost. Bun's sock.write() does a partial kernel write and silently drops the remainder. The Bun relay tracks unwritten bytes in a per-socket writeBuf: Uint8Array[] and flushes them in the drain handler.

// Bun: tail-queue what the kernel didn't accept
const n = sock.write(bytes)
if (n < bytes.length) st.writeBuf.push(bytes.subarray(n))

// drain handler: flush the queue
while (st.writeBuf.length > 0) {
  const chunk = st.writeBuf[0]!
  const n = sock.write(chunk)
  if (n < chunk.length) { st.writeBuf[0] = chunk.subarray(n); return }
  st.writeBuf.shift()
}

WebSocket proxy agent

CCR containers sit behind an egress gateway — direct outbound is blocked. The WS upgrade itself must go through an HTTP CONNECT proxy. Node's undici/globalThis.WebSocket does not consult the global dispatcher for upgrade requests, so the Node relay imports the ws npm package and passes an explicit agent. Bun's native WebSocket accepts a proxy URL directly.

getUpstreamProxyEnv() returns a record of env vars that subprocessEnv() merges into every child process spawned by the agent — Bash tool, MCP servers, LSP, git hooks. This ensures all subprocess traffic routes through the relay without per-tool configuration.

NO_PROXY: Anthropic API exclusion

The Anthropic API (api.anthropic.com) is listed three ways in NO_PROXY: as anthropic.com, .anthropic.com, and *.anthropic.com. This is because NO_PROXY parsing differs across runtimes — Bun and Go use glob match, Python urllib/httpx use suffix match. All three forms are required for reliable bypass.

Inherited proxy vars

Child CLI processes (e.g. a sub-agent spawned inside the session) cannot re-initialize the relay — the token file was already unlinked. If the parent's HTTPS_PROXY and SSL_CERT_FILE are both set in the environment, getUpstreamProxyEnv() detects this and passes all proxy vars through to grandchild processes, maintaining the chain.

Prompt injection and the token

A malicious prompt could instruct the agent to run gdb -p $PPID to read the session token off the heap. The prctl(PR_SET_DUMPABLE, 0) call (via Bun FFI into libc.so.6) blocks this — same-UID ptrace is rejected by the kernel after this call.

const PR_SET_DUMPABLE = 4
const rc = lib.symbols.prctl(PR_SET_DUMPABLE, 0n, 0n, 0n, 0n)
// Linux-only; silently no-ops on macOS/Windows

Dual authentication layers

The relay uses two separate credentials at two different points:

• WS upgrade: Authorization: Bearer <token> — authenticates the relay to the CCR gateway at the WebSocket protocol level.
• CONNECT tunnel: Proxy-Authorization: Basic base64(sessionId:token) — carried inside the first protobuf chunk, authorizes the specific upstream tunnel request.

The CCR sidecar has a 50-second idle timeout. The relay sends a ping every 30 seconds (PING_INTERVAL_MS = 30_000). Not all WebSocket implementations expose a ping() frame API, so the relay uses an application-level keepalive: a zero-length encodeChunk(new Uint8Array(0)) that the server ignores but which resets the idle timer. The pinger is stored in ConnState.pinger and cleared in cleanupConn().

forwardToWs() splits outbound data into chunks of at most MAX_CHUNK_BYTES = 512 * 1024 (512 KB). This is Envoy's per-request buffer cap. Git push payloads can exceed this; the chunking ensures they are streamed rather than rejected.

for (let off = 0; off < data.length; off += MAX_CHUNK_BYTES) {
  const slice = data.subarray(off, off + MAX_CHUNK_BYTES)
  ws.send(encodeChunk(slice))
}