ccproxy

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

Platform	Reverse proxy (ccproxy start)	WireGuard namespace jail (ccproxy run --capture)
Linux	✅	✅
Windows (WSL2)	✅	✅
macOS	✅	❌ — requires Linux namespaces

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