Skip to main content
kRouter

MITM capture

Route Claude Desktop, Antigravity, GitHub Copilot and Kiro IDE through kRouter when they have no base-URL setting. Setup, the four trust mechanisms, and clean teardown.


Most tools let you point them somewhere else. You set a base URL of http://localhost:20128/v1 and you are done.

Four do not. Claude Desktop, Google Antigravity, GitHub Copilot and Kiro IDE talk to fixed hostnames with nothing to configure. MITM capture routes them anyway, by catching the traffic on its way out of your machine.

Everything here happens locally. No traffic leaves your machine to reach kRouter, and the certificate kRouter generates is trusted only by your machine.

What it does

AppHostnames redirectedRequests re-routed
Claude Desktopapi.anthropic.com/v1/messages, and the token-count preview
Antigravitydaily-cloudcode-pa.googleapis.com, cloudcode-pa.googleapis.com:generateContent, :streamGenerateContent
GitHub Copilotapi.individual.githubcopilot.com/chat/completions, /v1/messages, /responses
Kiro IDEruntime.us-east-1.kiro.dev, q.us-east-1.amazonaws.com, codewhisperer.us-east-1.amazonaws.comGenerateAssistantResponse

Four pieces, all local: a hosts-file entry per hostname pointing at 127.0.0.1; a local root CA; a TLS server on port 443 that signs a leaf certificate per hostname on demand; and one decision per request. Chat requests for models you mapped go to your chosen provider. Everything else — sign-in, settings, telemetry, any model you did not map — passes straight through to the real service.

Cursor is not supported. Its requests leave from Cursor's own servers, so there is nothing local to intercept.

Before you start

Capture runs on the machine the app runs on. This is the thing people most often get wrong when they also run kRouter on a server. A kRouter in Docker on a VPS has no desktop IDE in front of it and nothing to intercept. If Antigravity is on your laptop, capture has to be on your laptop. The server install stays useful as the endpoint for everything else.

It does not work inside Docker. kRouter detects a container and says so, rather than pretending.

It needs admin rights to edit the hosts file and install a certificate: an administrator prompt on Windows, root or your sudo password on macOS and Linux.

Run it on the default data directory, or say that you mean it. Starting capture writes machine-wide trust as absolute paths inside DATA_DIR. A second instance started against a scratch DATA_DIR would repoint every Electron app on the machine at a certificate under a temporary path that disappears on cleanup, so kRouter skips those writes instead — and capture then cannot work from that instance.

A path cannot distinguish that from a single install that simply keeps its data in /var/lib/krouter, so you declare it: set KROUTER_ALLOW_MACHINE_TRUST=1 to tell kRouter this install owns the machine's trust configuration. It applies to teardown as well, and it is ignored when DATA_DIR sits inside the temp directory, which is never a permanent install. The start log names every surface it skipped and why.

Setup

  1. Open the dashboard's MITM page.
  2. Install the root certificate from the MITM Root Certificate card. You will be asked for admin rights.
  3. Start the MITM server.
  4. Start DNS for each app you want captured, from that app's card.
  5. Map the models. Each app has a mandatory default slot; point it at a model that currently answers.
  6. Fully quit and reopen the app. Not a window reload — see below.
  7. Send one real message and confirm it appears in kRouter's logs.

That last step matters more than it looks. The failure to watch for is a silent passthrough: capture shows as enabled, routes nothing, and the app's own subscription quietly pays for every turn while kRouter records no request at all.

The four trust mechanisms

Installing the CA into the operating system's trust store is the part everyone expects. It is also not sufficient on its own, because none of these four apps asks the operating system.

MechanismRuntimeEffectUsed by
OS trust storesystem toolsaddscurl, browsers
NODE_EXTRA_CA_CERTSNode, Electronadds to the OS storeClaude Desktop, Kiro, VS Code extensions
per-IDE caCertificatesthe IDE's own configaddsAntigravity
SSL_CERT_FILEGo, and Node from 26replaces the poolAntigravity's agy agent

kRouter writes all four. The word that matters is replaces.

Go's crypto/x509 treats SSL_CERT_FILE as the complete root pool. When it is set, the system trust store is not consulted at all — so a bundle exported by something unrelated hides the kRouter CA from every Go program on the machine. The usual culprit is a Python certifi line in a shell profile:

export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")

That bundle contains public roots and no kRouter CA, so Antigravity fails every call with x509: certificate signed by unknown authority while the three Node-based apps work perfectly. It looks exactly like certificate pinning and is not. The full account is here.

Not Go-only any more. Measured on macOS: Node 22.11, 22.21 and 24.14 ignore SSL_CERT_FILE, and Node 26 honours it — a bundle without the right root fails every TLS request the process makes. NODE_EXTRA_CA_CERTS still layers on top of whatever it left, so a bad value there is harmless while a bad SSL_CERT_FILE is not. Nothing in Node's own introspection shows the narrowed pool; only a handshake does.

kRouter handles this by generating a bundle of the system roots plus the kRouter CA and pointing SSL_CERT_FILE at it. Two rules follow from replaces, and both are deliberate:

  • The bundle is always a superset, never the CA alone. Pointing that variable at a single certificate would make every Go program on your machine — gh, docker, the Go toolchain — distrust the rest of the internet, and from Node 26 every Node and Electron process with it. kRouter refuses to write a bundle that looks implausibly small.
  • If something already set SSL_CERT_FILE, kRouter merges it rather than overriding it, so trust you chose is never narrowed.

On Windows none of this applies: Go uses the system certificate store, which the certificate install already populated.

Restart, do not reload

Environment variables are inherited when a process starts. A program that was already running keeps the values it launched with, no matter what is written afterwards.

So after enabling capture you need a new shell, and the IDE needs a full quit and reopen. A window reload keeps the same process tree and the same stale environment. kRouter prints a warning about this when it wires the variable; ignoring it is the most common cause of "I followed the steps and it still does not work."

Teardown

  1. Stop DNS, or Stop Server. This removes the hosts entries and flushes the DNS cache, which is what actually ends the interception. It deliberately leaves the certificate trusted, so starting again is instant.

    Step 2 works even if the certificate has already gone from the trust store — removed by hand, or a keychain cleaned — which is exactly when the blocks it strips would otherwise be left behind.

  2. Uninstall on the MITM Root Certificate card. This removes the certificate from the system trust store, strips the SSL_CERT_FILE block from your shell profiles, clears NODE_EXTRA_CA_CERTS (from 0.5.195), and deletes the per-IDE CA settings.

Removing the SSL_CERT_FILE block matters: left behind, it would pin every Go program on the machine to a bundle built around a certificate that no longer exists — worse than never having written it.

NODE_EXTRA_CA_CERTS is cleared from 0.5.195 onwards, the same way it was written — launchctl unsetenv on macOS, the HKCU\Environment value on Windows, the krouter block in the shell rc files, ~/.config/environment.d/95-krouter.conf and ~/.pam_environment on Linux. A stale value cannot break trust, because Node ignores a path with no file behind it, but it does make every Node and Electron process on the machine print Warning: Ignoring extra certs from ... on each TLS call. Like every other machine-wide surface, it is both written and cleared only for an install on the default data dir: a second instance must neither repoint the machine nor unset what it never wrote. On a scratch DATA_DIR kRouter wires no trust at all, so there is nothing to clear.

Uninstalling kRouter does not remove the certificate. Do step 2 first.

Security notes

  • Anyone who obtains rootCA.key can impersonate websites to your machine for as long as the certificate is trusted. Keep the data directory private, and do not copy the key into an image or a backup that syncs.
  • Treat capture as something you switch on while you use it and tear down when you are done, rather than something left running indefinitely.
  • Debug dumps of intercepted traffic are off unless you set DEBUG_MITM=1 or MITM_FILE_LOG=1, and sensitive headers are redacted in them.
  • Claude Code, Codex, GitHub Copilot, Antigravity and Kiro use subscription sessions that are not licensed for proxy or router use. The dashboard shows a risk notice before you connect them. Read each provider's terms before relying on this.

If something is wrong

Antigravity fails TLS, everything else works. Check echo $SSL_CERT_FILE. Any path there is the complete root pool for every Go program in that environment. See the trust section above.

Capture is on but nothing is routed. The app's model is probably not mapped, or the app is sending a model id that is not in the alias map, in which case the request passes through and the app's own account pays. Check kRouter's logs for the model id the app actually sent.

It worked before a reboot. Capture is restored on restart in current versions; if it is not, start the MITM server from the dashboard and re-check.

More in Troubleshooting and the interception guide.