Terminal
The engine behind the window also runs on its own in a terminal. It prints the traffic as it goes and can write a key log for Wireshark.
The app keeps it next to its own executable as zhttp-engine (zhttp-engine.exe on Windows). The examples call it zhttp.
zhttp -listen :8877 -keylog tls.keysOn start it prints the address, the steps to connect an iPhone, where the certificate is and what it decrypts. Ctrl C stops it.
Listening
Section titled “Listening”| Flag | Default | |
|---|---|---|
-listen |
:8877 |
Address and port to listen on |
-allow-public |
off | Accept clients from public addresses, not only your local network |
zhttp -listen :9000zhttp -listen 127.0.0.1:9000What to decrypt
Section titled “What to decrypt”| Flag | Default | |
|---|---|---|
-intercept |
every host | Decrypt only these hosts, comma-separated. The rest pass through, listed only with -v. |
-tunnel |
none | Pass these hosts through untouched. Wins over -intercept. |
-ca-dir |
the app’s folder | Where the certificate authority is kept |
-insecure |
off | Don’t verify servers’ certificates, for self-signed or private-CA servers |
-strict |
off | Refuse a connection rather than send a ClientHello that isn’t the app’s |
-tcp-profile |
none | Open connections to servers with an iPhone’s TTL, window scale and, on Windows, timestamps. The one value is ios. In the app, each session sets its own: see Fingerprints. |
-dns |
the system’s | Look servers’ names up with this DNS server: an IP address, tls:// and a host for DNS over TLS, or an https:// address for DNS over HTTPS |
Host patterns work as in SSL proxying: *.example.com also matches example.com.
zhttp -intercept "*.example.com,api.example.net"zhttp -tunnel "*.bank.example,pinned.example.com"zhttp -insecure -tcp-profile ioszhttp -dns 1.1.1.1zhttp -dns tls://dns.quad9.netzhttp -dns https://dns.quad9.net/dns-queryBy default -ca-dir is the folder the app uses (%AppData%\zhttp on Windows, ~/Library/Application Support/zhttp on macOS), so a device that trusts the app trusts the engine too.
Output
Section titled “Output”| Flag | Default | |
|---|---|---|
-v |
off | Also show ClientHello details and HTTP headers |
-vv |
off | Also show bodies |
-filter |
none | Only print traffic for hosts containing this text |
-body-bytes |
4096 |
Bytes of each body to print with -vv |
-max-body |
1048576 |
Bytes of each body to print or write with -out |
-out |
none | Also write every event, with bodies, to this file as JSON lines |
-keylog |
none | Write TLS secrets to this file for Wireshark |
-no-color |
off | Plain output. NO_COLOR set in the environment does the same. |
-color |
off | Colour even when the output isn’t a terminal, such as an IDE’s run window |
zhttp -v -filter example.comzhttp -vv -body-bytes 16384zhttp -out capture.jsonlWireshark
Section titled “Wireshark”zhttp -keylog tls.keysIn Wireshark: Preferences › Protocols › TLS › (Pre)-Master-Secret log filename › choose tls.keys. Captured TLS then decrypts.
AI agents
Section titled “AI agents”| Flag | |
|---|---|
-mcp-http |
Also serve agents over MCP at http://<addr>/mcp. Loopback addresses only. |
-mcp-stdio |
Serve one agent over MCP on stdin and stdout instead of printing traffic |
zhttp -listen :9000 -mcp-http 127.0.0.1:9878For an agent that starts the engine itself, such as Claude Code:
claude mcp add zhttp -- zhttp -listen :9000 -mcp-stdioWith MCP, every byte of every body is kept unless -max-body is given. See AI agents for what an agent can do. Rules such as breakpoints, maps and scripts live in the app, so their tools answer only when the app runs the engine.
| Flag | |
|---|---|
-version |
Print the version and exit |
-h |
List the flags |