ccproxy — CLI Proxy

Discord

ccproxy is a transparent network interceptor for LLM tooling and AI harnesses, built on mitmproxy and WireGuard with full TLS inspection and Wireshark keylog export. Originally purpose-built for Claude Code, ccproxy now works with any LLM client: Aider, Cursor, OpenAI SDK, or anything else that speaks HTTP. It jails a process inside a rootless WireGuard namespace, intercepts at the network layer, and feeds it through a DAG-driven pipeline that can decompose, transform, and re-route traffic between providers. Cross-provider request and response transformation is handled by lightllm, a surgical adapter and streaming-FSM layer inside ccproxy — no LiteLLM proxy subprocess, no gateway server.

New in 2.0: Codex/OpenAI Responses support with packaged request shaping, plus DeepSeek V4 routing for Anthropic-format requests through DeepSeek's /anthropic/v1/messages endpoint. See Configuration for the routing setup.

The hook pipeline is your extension point for building mods and taking control of your LLM usage while respecting terms of service:

• Cross-provider routing: redirect or transform requests between Anthropic, Gemini, OpenAI, DeepSeek, Perplexity Pro, and Anthropic-compatible forks.
• Compliance shaping: replay packaged, sanitized SDK compliance envelopes for built-in providers while injecting your actual request content at runtime.
• MCP bridging: add unsupported MCP features to any client: sampling via sentinel key detection, server notifications bridged into the LLM context via ccproxy’s /mcp endpoint, and experimental tasks support.

Feedback and contributions welcome — open an issue or submit a PR.

Installation

Platform support

WSL2 is fully supported because it is Linux. Native Windows is not — use WSL2. On macOS, the reverse proxy listener (ccproxy start + SDK use) works fine, but the namespace jail (ccproxy run --capture) requires Linux kernel features (unprivileged user/net namespaces, slirp4netns, iptables NAT) that have no macOS equivalent.

Windows via WSL2

The recommended Windows install is the ccproxy.wsl distro artifact. It is built on NixOS-WSL and includes ccproxy plus the Linux namespace tools required by ccproxy run --capture.

# Requires Store WSL 2.4.4 or newer.
wsl --update
wsl --version
wsl --install --from-file ccproxy.wsl
wsl -d ccproxy

Inside the distro:

ccproxy init
ccproxy start
ccproxy namespace status --json
ccproxy namespace doctor --json

Tier 1 Windows support is Windows 11 22H2+ with Store-distributed WSL2, systemd enabled, and mirrored networking recommended. Windows 10 and older WSL networking are best-effort. WSL1 and native Windows without WSL are unsupported.

Advanced users can still use Ubuntu on WSL2 with systemd and Nix, but the release artifact is the primary out-of-box path.

Linux

The WireGuard namespace jail needs a small set of system tools on PATH: slirp4netns, wireguard-tools (wg), iproute2 (ip), iptables, util-linux (unshare, nsenter), and procps (sysctl).

# Debian / Ubuntu
sudo apt update
sudo apt install -y slirp4netns wireguard-tools iproute2 iptables procps

# Fedora
sudo dnf install -y slirp4netns wireguard-tools iproute iptables-nft procps-ng

# Arch
sudo pacman -S slirp4netns wireguard-tools iproute2 iptables procps-ng

# NixOS — provided via the project devShell (`nix develop`)

Then install ccproxy:

# Recommended: uv tool (isolated venv, console scripts on PATH)
uv tool install ai-ccproxy

# Alternative: pip
pip install ai-ccproxy

On Ubuntu 24.04+, unprivileged user namespaces are restricted by AppArmor by default. Either run once:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

…or add a path-scoped AppArmor profile (see rootless-containers/rootlesskit).

macOS

Only the reverse proxy is supported. No system packages are required.

uv tool install ai-ccproxy
# or
pip install ai-ccproxy

ccproxy start and SDK use (ANTHROPIC_BASE_URL=http://localhost:4000) work the same as on Linux. ccproxy run --capture will fail fast with a clear error listing the missing Linux-only tools.

Verify

ccproxy --help
ccproxy init
ccproxy status --proxy --inspect    # exit 3 = both down (expected, nothing running yet)

Quick Start

# Initialize config template at ~/.config/ccproxy/ccproxy.yaml
ccproxy init

# Start the proxy and inspector stack (foreground)
ccproxy start

SDK use: point any OpenAI-compatible client at the reverse proxy listener:

export ANTHROPIC_BASE_URL=http://localhost:4000
claude -p "hello"

Transparent capture: run a command inside the WireGuard namespace jail (all traffic intercepted):

ccproxy run --capture -- claude -p "hello"

Architecture

Traffic enters through one of two listeners, passes through a fixed three-stage addon chain, and exits directly to the provider API.

flowchart TD
    subgraph Listeners
        RP["Reverse Proxy :4000"]
        WG["WireGuard CLI"]
    end
    RP --> Chain
    WG --> Chain
    subgraph Chain["Addon Chain"]
        IN["inbound<br/>DAG hooks"] --> TX["transform<br/>lightllm"] --> OUT["outbound<br/>DAG hooks"]
    end
    Chain --> API["Provider API"]

Addon chain (fixed order): ReadySignal → InspectorAddon → FingerprintCaptureAddon → MultiHARSaver → ShapeCaptureAddon → inbound DAG → transform → outbound DAG → TransportOverrideAddon → AuthAddon → GeminiAddon → PerplexityAddon → EgressSanitizerAddon

AuthAddon and GeminiAddon sit after the outbound pipeline so they see ccproxy-finalized requests/responses. AuthAddon owns 401-detect → refresh → replay. GeminiAddon owns Gemini capacity fallback (sticky retry + fallback chain on 429/503) and cloudcode-pa envelope unwrapping.

lightllm converts request and response bodies through ccproxy's own adapter layer and streaming FSMs. URL rewriting and auth injection are owned by the inspector route and Provider config, while lightllm owns wire-format conversion.

SSE streaming: SSEPipeline handles cross-provider streaming by parsing SSE events into ccproxy's response IR and rendering each chunk back to the listener's wire format.

Configuration

ccproxy init writes a template to ~/.config/ccproxy/ccproxy.yaml. Config is also read from $CCPROXY_CONFIG_DIR/ccproxy.yaml.

ccproxy:
  port: 4000

  # Provider entries keyed by sentinel suffix. The sentinel key
  # sk-ant-oat-ccproxy-{name} resolves to providers[name] for token
  # injection and routing.
  providers:
    anthropic:
      auth:
        type: command
        command: "jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json"
      host: api.anthropic.com
      path: /v1/messages
      type: anthropic

    deepseek:
      auth:
        type: command
        command: "printenv DEEPSEEK_API_KEY"
        header: x-api-key
      host: api.deepseek.com
      path: /anthropic/v1/messages
      type: anthropic

  hooks:
    inbound:
      - ccproxy.hooks.inject_auth
      - ccproxy.hooks.extract_session_id
    outbound:
      - ccproxy.hooks.gemini_cli
      - ccproxy.hooks.pplx_stamp_headers
      - ccproxy.hooks.inject_mcp_notifications
      - ccproxy.hooks.verbose_mode
      - ccproxy.hooks.shape
      - ccproxy.hooks.commitbee_compat

  lightllm:
    # Optional regex-matched override rules layered on top of the
    # sentinel-driven providers map. Default is empty: most routing
    # comes from `providers` via inject_auth's sentinel detection.
    transforms:
      - match_path: ^/v1/chat/completions
        match_model: ^gpt-4o
        action: transform
        dest_provider: anthropic
        dest_model: claude-haiku-4-5-20251001

Transform matching: match_host (optional regex, checked against pretty_host + Host header + X-Forwarded-Host), match_path (regex, default .*), match_model (regex, optional). First match wins. Three actions: redirect (default — rewrite destination, preserve body), transform (cross-format via lightllm), passthrough (forward unchanged). Auth resolves through dest_provider → providers[name].

Auth source types

Provider.auth dispatches on type:. Two static loaders return whatever the underlying source holds; OAuth loaders own the refresh lifecycle in-process.

command and file are not OAuth — they have no expiry awareness and never call out to a refresh endpoint. ccproxy reads them on every resolve; rotation happens out