/using-ccproxy-inspector

name: using-ccproxy-inspector
description: >-
  Operates the ccproxy inspector MITM system for intercepting, inspecting, and
  transforming LLM API traffic. Covers running CLI tools through the reverse
  proxy or permissive WireGuard namespace capture path, checking namespace
  status and doctor output, inspecting flows with client-vs-forwarded request
  comparison, understanding the inbound/transform/outbound pipeline, capturing
  and auditing shape artifacts, applying the privacy guide, and diagnosing flow
  issues. Use when running CLI applications through ccproxy, inspecting
  intercepted flows, comparing client request vs forwarded request, checking
  shaping profile status, using WireGuard namespace capture, explaining privacy
  behavior, or debugging the hook pipeline.

Using the ccproxy Inspector

The inspector intercepts LLM API traffic through mitmproxy and routes accepted flows through the ccproxy addon chain:

InspectorAddon -> FingerprintCaptureAddon -> MultiHARSaver -> ShapeCaptureAddon
               -> inbound DAG -> transform router -> outbound DAG
               -> TransportOverrideAddon -> AuthAddon -> GeminiAddon
               -> PerplexityAddon -> EgressSanitizerAddon

Use the `using-ccproxy-api` skill for provider auth, sentinel keys, SDK base URL configuration, native `ccproxy.yaml` setup, and sibling `config.yaml` model routing when applicable.

The ccproxy plugin does not install or register the ccproxy FastMCP server for the user. If an MCP-aware client should use ccproxy's flow-inspection tools, the user must add their own MCP server config pointing at the running daemon's `http://127.0.0.1:<mcp-port>/mcp` endpoint and supply its bearer token when configured. Keep plugin installation separate from MCP server registration.

Inspect First

Before debugging a flow, establish which process and config directory are in play:

ccproxy status
ccproxy status --json
ccproxy status --proxy --inspect --mcp

For namespace work, also inspect the transparent capture path:

ccproxy namespace status
ccproxy namespace status --json
ccproxy namespace doctor
ccproxy namespace doctor --json

Interpretation:

• `namespace status` reports implementation facts: permissive mode, generated

WireGuard config presence, slirp4netns topology, and required tool paths.

• `privacy_claim: false` is intentional. ccproxy reports observable runtime

behavior; it does not claim that the namespace is a restrictive privacy firewall.

• `namespace doctor` runs a live probe through the same namespace execution path

used by `ccproxy run --capture`.

• `namespace doctor` fails for DNS, public IPv4, or ccproxy-localhost

reachability failures. IPv6 is reported but is not a failure.

• `ccproxy namespace wireguard-config` prints raw WireGuard client config and

can expose private key material. Do not print or share it casually.

When the task concerns privacy, security language, namespace guarantees, keylogs, flow exports, or sharing diagnostics, read `docs/privacy.md`.

Running Tools Through ccproxy

Reverse proxy: `ccproxy run`

Use this when the client honors SDK base URL environment variables:

ccproxy run -- claude
ccproxy run -- aider
ccproxy run -- python my_agent.py

This sets `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, and `OPENAI_API_BASE` to the configured ccproxy reverse proxy listener. Only traffic addressed to ccproxy is intercepted.

Use for lightweight SDK debugging and normal OpenAI/Anthropic-compatible clients.

WireGuard namespace capture: `ccproxy run --capture`

Use this when the tool hardcodes provider endpoints, when base URL injection is not enough, or when you need reference traffic from a real provider CLI:

ccproxy start
ccproxy run --capture -- claude -p "hello"
ccproxy run --capture -- aider --model claude-sonnet-4-5-20250929
ccproxy run --capture -- python my_agent.py

The subprocess runs in a rootless Linux user+network namespace. ccproxy configures a WireGuard client inside that namespace, routes the namespace default route through mitmproxy, and injects a combined CA bundle via:

SSL_CERT_FILE
NODE_EXTRA_CA_CERTS
REQUESTS_CA_BUNDLE
CURL_CA_BUNDLE

Important behavior:

• The namespace path is permissive by default because ccproxy is a development

tool.

• Unmatched WireGuard traffic passes through to its original destination.
• Namespace localhost is DNATed through the slirp4netns gateway so tools with

hardcoded `127.0.0.1:4000` can still reach ccproxy.

• A port-forwarding monitor uses the slirp4netns API to expose namespace

listeners back to the host, which supports OAuth callback workflows.

• Do not describe this path as a default deny privacy sandbox.

Choosing A Capture Mode

| Scenario | Prefer | | --- | --- | | SDK client supports configurable base URL | `ccproxy run` | | CLI hardcodes provider endpoints | `ccproxy run --capture` | | Need native provider CLI reference traffic | `ccproxy run --capture` | | Need minimum moving parts | `ccproxy run` | | Need full local network capture for a tool | `ccproxy run --capture` | | Need to explain privacy behavior | `docs/privacy.md` + `ccproxy namespace status --json` |

Understanding Flow State

Every accepted reverse-proxy or WireGuard flow is `direction="inbound"`. The pipeline stage names `inbound`, `transform`, and `outbound` describe processing order, not traffic direction.

`InspectorAddon` stamps source metadata:

| Source | Meaning | | --- | --- | | `reverse` | Request entered through the reverse proxy listener | | `wireguard` | Request entered through mitmproxy's WireGuard listener | | `unknown` | Default before source is stamped |

Every flow has these useful views:

• **Client request**: pre-pipeline snapshot of what the client sent.
• **Forwarded request**: post-pipeline request ccproxy intended to send

upstream.

• **Provider response**: raw provider response before response-side transform

when captured.

U