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
