Skip to content

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.keys

On start it prints the address, the steps to connect an iPhone, where the certificate is and what it decrypts. Ctrl C stops it.

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 :9000
zhttp -listen 127.0.0.1:9000
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 ios
zhttp -dns 1.1.1.1
zhttp -dns tls://dns.quad9.net
zhttp -dns https://dns.quad9.net/dns-query

By 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.

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.com
zhttp -vv -body-bytes 16384
zhttp -out capture.jsonl
zhttp -keylog tls.keys

In Wireshark: Preferences › Protocols › TLS › (Pre)-Master-Secret log filename › choose tls.keys. Captured TLS then decrypts.

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:9878

For an agent that starts the engine itself, such as Claude Code:

claude mcp add zhttp -- zhttp -listen :9000 -mcp-stdio

With 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