starbaser/ccproxy: a mitmproxy and WireGuard jail for Claude Code traffic

What starbaser/ccproxy actually intercepts

The problem ccproxy addresses is that LLM clients are closed at the transport layer. If you want to send a Claude Code request to Gemini, strip a field before it leaves your machine, or replay a request through a different provider, you normally have to patch the client or run a separate gateway process. ccproxy takes the network path instead. The README describes it as "a transparent network interceptor for LLM tooling and AI harnesses, built on mitmproxy and WireGuard with full TLS inspection and Wireshark keylog export."

The intended audience is narrow but real: engineers building what the project calls mods, people who want to control model routing with their own logic, and anyone who needs to observe what an agent CLI sends. It is not a general-purpose forward proxy for a corporate network, despite the name overlap with a much older Windows product.

Two listeners, one fixed addon chain

Traffic enters ccproxy through one of two listeners. The reverse proxy listens on port 4000 and is what SDK-style clients talk to. The WireGuard listener is what the namespace jail uses, and it captures everything a child process sends without the process knowing.

From there, both paths converge on a fixed addon chain. The README lists the order explicitly: ReadySignal, InspectorAddon, FingerprintCaptureAddon, MultiHARSaver, ShapeCaptureAddon, the inbound DAG, the transform stage, the outbound DAG, TransportOverrideAddon, AuthAddon, GeminiAddon, PerplexityAddon, EgressSanitizerAddon. The inbound and outbound DAGs are the extension point, which is where the project's mod concept lives.

Two details are worth noting because they shape what you can build. AuthAddon and GeminiAddon sit after the outbound pipeline, so they see ccproxy-finalized requests rather than raw client traffic. AuthAddon owns the 401-detect, refresh, replay cycle, and GeminiAddon owns capacity fallback on 429 and 503 plus cloudcode-pa envelope unwrapping. If you write a hook that assumes it sees the final bytes, it does not.

Wire-format conversion is handled by an internal layer the README calls lightllm, described as "a surgical adapter and streaming-FSM layer inside ccproxy." The README states that LiteLLM is not a runtime dependency, which distinguishes this from gateway designs that shell out to a separate proxy process.

Installing ccproxy with uv and pointing a client at it

The README gives two install paths. The recommended one uses uv, which puts console scripts on PATH in an isolated virtual environment. The package name on PyPI is ai-ccproxy, not ccproxy.

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

After install, initialize the configuration and start the stack in the foreground. The init step writes both ccproxy.yaml and a LiteLLM-compatible config.yaml.

ccproxy init
ccproxy start

To use it as a reverse proxy, point an Anthropic-compatible client at the listener on port 4000. The README uses the claude CLI as the example.

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

If you want transparent capture instead, wrap the command in the namespace jail. Every request the child process makes is intercepted.

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

To confirm the stack is up, the README suggests a status check with an explicit note about the exit code: `ccproxy status --proxy --inspect` returns 3 when both proxy and inspector are down, which is expected before you start anything.

The macOS and Windows limits are kernel limits, not bugs

The platform table in the README is unusually honest. Linux supports both the reverse proxy and the namespace jail. Windows is supported through WSL2, which the README treats as Linux. macOS supports only the reverse proxy, and `ccproxy run --capture` fails fast with an error listing the missing Linux-only tools.

The reason given is concrete: the jail needs unprivileged user and net namespaces, slirp4netns, and iptables NAT, none of which have a macOS equivalent. This is the single most important constraint to check before adopting. A macOS user gets the routing and transformation pipeline but not the transparent capture, which is half the product's premise.

There is a second Linux caveat. On Ubuntu 24.04 and later, AppArmor restricts unprivileged user namespaces by default. The README offers two fixes: a one-time sysctl, or a path-scoped AppArmor profile following the rootlesskit documentation.

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

On the Linux side the jail also needs system tools on PATH: slirp4netns, wireguard-tools, iproute2, iptables, util-linux, and procps. The README lists apt, dnf, and pacman commands for these, and notes that NixOS gets them through the project devShell.

Where ccproxy is the wrong tool

ccproxy is not a drop-in replacement for a general HTTP proxy, and the name collision with the long-standing Windows CCProxy server causes real confusion. Search data for this project is dominated by people looking for a Windows proxy server with FTP support, a downloadable .exe, and Android or iOS clients. starbaser/ccproxy is a Python package installed through uv or pip, it has no mobile clients, and the README does not describe FTP proxying at all. If that is what you want, you are on the wrong repository.

The second case is production gateway duty. ccproxy performs TLS interception by design and exports Wireshark keylogs. That is a debugging and development posture. Running it in front of production traffic means every request body is decryptable by the process, and the README's compliance shaping feature, which replays sanitized SDK envelopes and injects your content at runtime, is exactly the kind of behavior that needs a terms-of-service review before you deploy it anywhere real. The README frames the hook pipeline as an extension point "while respecting terms of service," which reads as a warning rather than a guarantee.

A third limit is dependency weight. The pyproject.toml pulls in mitmproxy, pydantic-ai-slim with Anthropic, Google, and OpenAI extras, pydantic-graph, curl-cffi, and httpx-curl-cffi, and requires Python 3.13 or newer. That is a large surface for a tool you may only want for request rewriting.

ccproxy compared with LiteLLM as a gateway

The obvious alternative for cross-provider routing is LiteLLM, and the comparison is not close in design. LiteLLM runs as a gateway server that your client points at; routing happens at the application layer, and the client must be configured to use it. ccproxy intercepts at the network layer instead, so a process that hardcodes an Anthropic endpoint can still be redirected, particularly inside the WireGuard jail.

The trade-off runs the other way too. A gateway server is a normal HTTP service you can deploy, scale, and monitor with standard tooling. ccproxy is a local interceptor with a fixed addon chain and a DAG pipeline, and its configuration lives in ccproxy.yaml plus a LiteLLM-compatible config.yaml. The README states that LiteLLM itself is not a runtime dependency, so you are not running both, but you are also not getting LiteLLM's provider matrix or its operational story. If your need is centralized routing for many services, a gateway is the better shape. If your need is to see and rewrite what one CLI agent sends, ccproxy is the better shape.

Maintenance, licence, and the cost of upgrading

The default branch is dev and the last push was on 2026-08-10, which is recent enough that the repository is not dormant. The release history is less settled. v2.0.0-rc1 was tagged on 2026-04-16, and the previous stable release, v1.2.0, was tagged on 2025-12-06. The README badge says version 2.0.0 while the latest release listed is a release candidate, so anyone pinning versions should expect the 2.0 line to still be moving.

The licence situation needs attention. pyproject.toml declares `license = { text = "AGPL-3.0-or-later" }`, while the repository metadata reports NOASSERTION. The repository has a LICENSE file at the top level, but its contents cannot be confirmed here. AGPL matters if you plan to offer a modified ccproxy as a network service, since that is the scenario the licence is written for. This is not legal advice; read the LICENSE file and decide with whoever handles licensing on your side.

Upgrade cost is mostly configuration drift. `ccproxy init` generates ccproxy.yaml and a LiteLLM-compatible config.yaml, and the README notes that 2.0 added Codex and OpenAI Responses shaping plus DeepSeek V4 routing through DeepSeek's /anthropic/v1/messages endpoint. If you have customized the DAG hooks or the shapes directory, a major version bump is where those customizations will need attention. The repository includes a CHANGELOG.md and a docs/ directory, and those are the files to read before moving between minor versions.

Editorial conclusion

Adopt starbaser/ccproxy if you run Linux or WSL2 and need to rewrite LLM requests between providers, or if you want a transparent capture jail around a CLI agent. Do not adopt it on native macOS or Windows if you need ccproxy run --capture, since the namespace jail requires Linux kernel features. Before committing, verify three things: that your platform tier is supported, that the AGPL-3.0-or-later licence fits your distribution plans (the repository LICENSE file and pyproject.toml disagree on the identifier, and this is not legal advice), and that the hook pipeline you need is documented in docs/ rather than only in the source tree.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. starbaser/ccproxy on GitHub