TLS interception (MITM)

merido can run a TLS-intercepting proxy that captures the traffic of supported coding CLIs (Cursor, Copilot, Antigravity, Kiro) so it flows through the gateway — letting you route those tools to your own providers and apply token-saving. Interception works by issuing a local CA, generating certificates on the fly, and pointing the tool's hostnames at 127.0.0.1.

Use on machines you control

Intercepting TLS means installing a custom root CA and rewriting /etc/hosts. Only do this on machines you own and understand. Some upstreams' terms of service may restrict proxying or fingerprint-shaping their clients — interception (and the related antiban helpers) exist for interoperability; use them only where you accept that risk. The CA's private key is written 0600 and never served.

Enabling

MITM is configured at startup, not from the dashboard. Set:

• MERIDO_MITM_ENABLED=true — start the intercepting proxy.
• MERIDO_MITM_MANAGE_HOSTS=true — (optional) let merido add the managed block to /etc/hosts.
• MERIDO_MITM_INSTALL_CA=true — (optional) install the CA into the OS trust store.

The host-file and trust-store steps require elevated privileges; if they fail, merido logs the error and keeps running (the proxy still starts). When the gateway requires API keys, MITM mints a dedicated internal proxy-scoped key (shown as "MITM (internal)" in the Keys list) so rewritten requests can authenticate.

CA management

GET /api/mitm/status   # enabled?, port, managed hosts, CA presence + fingerprint
GET /api/mitm/ca       # download the public CA certificate (PEM)

• Status reports whether interception is on, the proxy port, the managed hosts, and — once a CA exists — ca_present and the CA fingerprint.
• Download returns the CA's public certificate as a PEM attachment (merido-mitm-ca.pem). The first download generates and persists the CA (cert + private key) under data_dir/mitm/ if it doesn't exist yet.

Verify the certificate

After downloading, compare the certificate's SHA-256 fingerprint against the ca_fingerprint shown by GET /api/mitm/status before trusting it. The status fingerprint is the authoritative value to check against the cert you're about to install.

Remove / untrust

To stop trusting the CA, remove the merido CA from your OS trust store the same way you'd remove any root certificate (e.g. Keychain Access on macOS, the NSS DBs on Linux). On a clean shutdown merido strips its managed block from /etc/hosts automatically, so hostnames stop being redirected.

Host management

The set of intercepted hostnames is fixed per supported tool (Cursor, Copilot, Antigravity, Kiro) rather than edited via an API. When MERIDO_MITM_MANAGE_HOSTS=true, merido maintains a clearly delimited block in /etc/hosts that points those hostnames at 127.0.0.1:

# >>> merido-mitm
127.0.0.1 api2.cursor.sh
127.0.0.1 cloudcode-pa.googleapis.com
# <<< merido-mitm

The block is owned entirely by merido and is removed on graceful shutdown.

Related

• Connect a coding CLI — the non-intercepting way to point tools at merido.
• Credential policy, vault & proxy pools — the antiban helpers that pair with interception.
• Exposing the gateway with a tunnel — the other networking feature.