mitmproxy on Mac: inspect one site’s HTTPS

You can inspect one site’s HTTPS traffic with mitmproxy without changing your Mac’s system proxy. Run mitmproxy locally, then use Firefox’s PAC setting to send one hostname through it and all other requests directly. The mitmproxy tutorial below uses example.com as a placeholder; replace it with the exact host you need.

Which mitmproxy tool should you open?

How to use mitmproxy depends on the interface you want: mitmproxy for an interactive terminal, mitmweb for a graphical browser interface, or mitmdump for output you can pipe or script. All three start in regular HTTP proxy mode on port 8080 by default, per mitmproxy’s getting-started guide (checked October 2026), and any of them can run any proxy mode (checked October 2026). mitmproxy’s own sample output shows the listener on all interfaces (*:8080), so on a shared network add --listen-host 127.0.0.1.

I ran mitmproxy --version and mitmdump --help on October 4, 2026. The installed build reported 12.2.3. Its help lists --allow-hosts HOST, --ignore-hosts HOST (both take regular expressions) and --listen-host HOST. The recipe uses mitmproxy so you can see requests arrive and inspect them in the terminal.

Install mitmproxy and scope HTTPS inspection

On macOS, the project recommends installing its cask with Homebrew. Run this on a Mac with Homebrew installed:

brew install --cask mitmproxy

That install command is from the mitmproxy installation docs (checked October 2026). A successful Homebrew install makes mitmproxy, mitmweb, and mitmdump available. After installation, start the proxy with a host filter. Replace example.com with your target’s domain:

mitmproxy --listen-host 127.0.0.1 --allow-hosts '(^|\.)example\.com:443$'

The terminal should show that the proxy is listening on port 8080. The expression matches example.com:443 and its subdomains on HTTPS; shop-example.com does not match. mitmproxy applies --allow-hosts to proxy traffic, ignoring other hosts, as described in its domain filtering guide (checked October 2026). This filter limits what mitmproxy processes; the Firefox PAC rule limits which requests are sent to it in the first place.

Route one site from Firefox only

A PAC file is a small JavaScript function that chooses a proxy separately for each URL. Firefox has its own proxy configuration, so this recipe affects Firefox and leaves macOS’s system proxy alone. Mozilla documents .pac files and local file: URLs in Firefox connection settings (checked October 2026); PAC host matching and return values are covered in MDN’s PAC guide (checked October 2026).

Save this as mitmproxy-one-site.pac somewhere in your home folder. Change both occurrences of example.com to the target domain, keeping the leading dot in the second comparison:

function FindProxyForURL(url, host) {
	if (
		url.substring(0, 6) === 'https:' &&
		(host === 'example.com' || dnsDomainIs(host, '.example.com'))
	) {
		return 'PROXY 127.0.0.1:8080';
	}
	return 'DIRECT';
}

In Firefox’s settings (checked October 2026), open Firefox > Settings > Privacy and security > Connection and software security > Advanced settings > Proxy settings > Configure proxy. Choose Automatic proxy configuration URL, enter the file URL for your saved PAC file (for example, file:///Users/yourname/mitmproxy-one-site.pac), then click OK.

When you visit https://example.com, its HTTPS connection should appear in mitmproxy. Visit another site in Firefox: it should load directly and produce no flow there. The PAC file matches the root hostname and subdomains, but the mitmproxy filter only decrypts HTTPS on port 443 for that domain.

Trust the mitmproxy certificate in macOS 27

The first run creates a unique certificate authority under ~/.mitmproxy. Its mitmproxy-ca-cert.pem file is the public certificate to trust; mitmproxy-ca.pem also contains the private key, so never import or share that file. mitmproxy’s certificate guide (checked October 2026) documents these filenames and the default folder.

For macOS 27, open Keychain Access from Spotlight, select the login keychain, and drag ~/.mitmproxy/mitmproxy-ca-cert.pem into the app. Select the imported mitmproxy certificate, double-click it, expand Trust, and set the SSL trust policy to Always Trust. Apple’s macOS 27 Keychain Access guide, certificate import steps, and trust settings steps support those current paths and controls; Apple defines Always Trust in its certificate trust policy guide for macOS 27.

Since Firefox 120, Firefox imports user-added certificates from the macOS root store by default, per Mozilla’s Firefox 120 release notes (2023).

The test is one successful load of your target without a certificate warning, with its request and response visible in mitmproxy. A trusted MITM CA can read TLS traffic that is routed through its proxy. Keep the PAC narrow and remove the CA when your inspection is done.

Fix the common failures

Use the error to decide which layer to repair:

Symptom	Likely cause	Fix
Firefox shows an unknown issuer or certificate warning	The browser does not trust mitmproxy’s CA yet	Check the mitmproxy certificate is in the login keychain with SSL set to Always Trust; restart Firefox and reload the target. For a site the browser already knows as an HSTS host, RFC 6797 (2012) requires it to terminate the connection when certificate validation fails, so there is no click-through.
One app or hostname fails while other pages work	Certificate pinning rejects the generated certificate	Do not disable certificate checks. If you do not need that host’s contents, add it to `--ignore-hosts`; it will pass through without decryption. Otherwise inspect only an app you control and use its documented debug configuration.
The target never appears in mitmproxy	Firefox did not load the PAC file, the PAC host does not match, or the application ignores Firefox’s proxy	In Firefox’s connection settings, reload the PAC URL and verify the target spelling. Apps that do not use Firefox’s proxy need their own proxy setting; this recipe does not capture arbitrary Mac applications.

The ignore_hosts behavior and pinning limitation are documented in mitmproxy’s domain filtering guide (checked October 2026). For an --ignore-hosts example, use an exact host-and-port pattern with escaped dots, such as '^pinned\.example:443$'. It tells mitmproxy to forward that TLS connection without processing its contents; it cannot reveal pinned traffic. HSTS is a browser rule that enforces HTTPS: for a known HSTS host, RFC 6797 (2012) has the browser terminate the connection when secure transport validation fails, so the useful correction is to trust the intended local CA, not weaken browser TLS checks.

Choose mitmproxy, Charles, or Proxyman

For one-site capture, all three can inspect HTTPS after the client trusts their CA. Choose by how you want to work: mitmproxy is the free terminal-and-Python alternative to Charles Proxy; between the two paid apps (Proxyman vs Charles), Charles pairs a GUI with rule-based rewrites, while Proxyman sells a GUI license that includes scripting. Prices and platform claims below are from vendor pages checked October 4, 2026.

Tool	License and price (checked October 2026)	Desktop platforms	Scripting or rule changes
mitmproxy	MIT-licensed, free and open source	macOS, Windows, Linux	Python addons can modify requests and responses.
Charles	30-day trial; USD $50 per user license for 1–4 users	macOS, Windows, Linux	Rewrite rules change headers, URLs, query values, or bodies.
Proxyman	Standard perpetual license, USD $89 for one device; includes one year of updates	macOS, Windows, Linux	Scripting is included with its premium features.

The mitmproxy project page describes it as free and open source, and its addon guide shows Python scripts. Charles lists price and trial terms on its license page and documents Rewrite rules. Proxyman publishes platform, price, license term, and scripting details on its pricing page. These are product-page snapshots, not a promise that future prices or license terms will stay the same.

Use Octoweb if per-site routing is the missing piece

I build Octoweb, so weigh that accordingly. If you already use it, Settings > Proxies can send only listed sites through an HTTP proxy such as mitmproxy; other tabs connect directly. Proxied sites use a separate cookie store, so expect to sign in again there. This feature requires macOS 14 or later. Those are Octoweb facts from the current product record; they do not change mitmproxy’s certificate requirement. See Octoweb’s install options if you want to try that route.

Undo the proxy and remove its CA

Clean up in this order so Firefox stops sending traffic to a proxy that is no longer running:

In Firefox’s settings (checked October 2026), open Firefox > Settings > Privacy and security > Connection and software security > Advanced settings > Proxy settings > Configure proxy, select No proxy, and click OK.
In the mitmproxy terminal, press ⌃C, then answer y at the Quit prompt to stop the listener.
Open Keychain Access, select the login keychain, find the certificate named mitmproxy, and delete it (select it, then press Delete). Do not delete the whole keychain. Apple’s Keychain Access guide covers finding items in a keychain.
Delete mitmproxy-one-site.pac from your home folder if you no longer need it.

If you need the SSH variant of routing just one site, the Mac SOCKS proxy guide covers that separate setup.