Whistle client: a desktop shell for the Whistle debugging proxy

A GUI wrapper around a command line proxy

Whistle is a cross-platform network capture and debugging tool. The avwo/whistle-client repository is the official desktop client for it, and the distinction matters for anyone deciding what to install. The client is an Electron application whose package manifest names the app Whistle, with an appId of whistle.client, a main entry point at ./lib/index.js, and a start script that runs electron ./lib. It is a shell and a configuration surface wrapped around the proxy, not a different engine.

The supported platforms are macOS on both Apple Silicon and Intel, Windows, and Linux on Fedora and Ubuntu. Builds are produced with electron-builder, and the artifact naming pattern is derived from the product name, version, operating system, and architecture, so a macOS ARM build is a .dmg and a Windows build is a .exe produced through an NSIS installer, while Linux produces an AppImage for x86_64 and arm64. The mac build also sets LSUIElement, which keeps the client out of the dock as a persistent background tool, and the Windows installer is configured for a per-machine install that lets the user change the installation directory and launches the app after the install finishes.

The client is where the everyday toggles live, and the project also states clearly that on a headless server or an unusual device you should use the command line version of Whistle instead, at the avwo/whistle repository.

Root CA and system proxy: the two steps you must take first

The documentation is clear that two initial steps are required on first run. From the Whistle menu at the top of the client you choose Install Root CA, which installs a system root certificate used to parse HTTPS requests, and then you enable Set As System Proxy, which sets the system proxy so the client captures the system's web requests. The top menu is a small set of named entries: Proxy Settings, Install Root CA, Check Update, Set As System Proxy, Start At Login, Restart, and Quit. Start At Login controls whether the client starts automatically with the system, and Check Update looks for a new version.

This is the part of the workflow with real consequences, and it is where a debugging proxy differs from a normal application. Decrypting HTTPS requires a trusted root certificate in the operating system trust store, and a certificate that the system trusts can decrypt traffic for any application on the machine, not just your browser. Corporate endpoint security products sometimes flag the client during installation, and the guidance is to allow the first launch, or to ask IT to whitelist Whistle if the block persists.

The other consequence is visible in the project's own troubleshooting section. Once the system proxy is on, applications that do their own network handling, with Outlook and Word named as examples, can start failing to connect. The documented diagnosis is to look for captureError entries in the capture interface and add the affected domains to the bypass list.

Proxy Settings and the bypass list

The Proxy Settings panel holds the knobs that matter for a capture session, and one of them is mandatory. Proxy Port is a required field with a default of 8888. Socks Port adds a SOCKSv5 proxy port. Bound Host selects the network interface the listener binds to, which is the setting you reach for when a machine has several interfaces and you want the proxy to be reachable from elsewhere on the network. Proxy Auth sets a username and password pair that requests passing through the proxy must present. Bypass List is a set of domains that should not go through the proxy, and it accepts three forms:

127.0.0.1
www.test.com
*.test.com

The IP form matches a single address, the domain form matches one host, and the wildcard form covers all subdomains of the named domain, as the documentation says for *.test.com. A sixth option, Use whistle's default storage directory, switches the client to the command line version's directory so that previously saved configuration is preserved, and the documentation warns that the command line instance has to be stopped first or the two will overwrite each other's configuration.

That storage directory point is the one to understand before you migrate. The client uses its own storage directory by default, so your rules, plugins, and settings do not carry over from a previous command line installation unless you flip this switch. The same warning appears again later in the documentation, which states that only one Whistle instance may access that directory at a time, since multiple instances running together cause configuration conflicts and data overwrites.

Plugin installation from inside the client

Plugins are managed from a Plugins tab in the left navigation, where the Install button opens a dialog for naming the plugins to add. Several plugins can be installed at once, separated by spaces or newlines, and a custom npm registry can be chosen either by appending a registry argument to the plugin name or by picking a previously used mirror from a dropdown list. The documentation gives a concrete example, installing two plugins from a domestic mirror:

w2 install --registry=https://registry.npmmirror.com whistle.script whistle.inspect

The mechanism is worth understanding because it explains the relationship between the client and the command line tool. The command shown is a w2 invocation typed into the client's install dialog, which shows the client accepts command line style plugin installs. The registry override matters in practice for users behind a slow or blocked default npm source, and the dropdown of remembered mirrors means the choice is remembered across sessions.

The plugin names in the example, whistle.script and whistle.inspect, illustrate the shape of the extension mechanism: plugins are npm packages, so the plugin ecosystem follows the npm registry rather than a bespoke catalogue.

Updates, releases, and where the client ends

Updates come in two forms. The Check Update entry in the Whistle menu looks for a new version and walks you through the update, and the fallback is to download the latest build from the GitHub Releases page and install it again following the same steps as the original installation. The release history is steady: version 1.6.12 was published on 2026-10-11, 1.6.11 on 2026-09-14, and 1.6.10 on 2026-08-16, and the last push to the repository was on 2026-10-19. Patch releases roughly every three to four weeks is the observed rhythm, which is what you would expect for a tool that tracks a changing underlying proxy.

The client itself is a bounded thing. It covers installation, the root CA workflow, the system proxy switch, global settings, the plugin manager, and update checks. It does not replace the command line version, and the documentation points at the official Whistle documentation site for detailed usage guides and examples, at wproxy.org/docs/getting-started.html. Anything beyond the GUI and its settings, such as rule authoring, is documented there rather than here.

One install path deserves a note for Windows users. The recommended standard installer requires administrator rights and supports the full feature set, including the whistle://client pseudo-protocol, while the user installer, which does not need administrator rights, has the limitation that it does not support pseudo-protocol invocation. The pseudo-protocol registration is declared in the build configuration as a custom scheme named whistle, which is how a browser or another application can hand a request to the proxy.

Editorial conclusion

Adopt the Whistle client if you need to inspect HTTP, HTTP2, HTTPS, and Websocket traffic on a desktop with a GUI and want the same proxy engine you already use from a terminal. Do not adopt it on a headless server, where the documentation points you at the command line version instead. Verify first that your enterprise security software permits the root CA installation, because that is the step most likely to be blocked.

Frequently asked questions

Official sources

1. avwo/whistle-client on GitHub
2. Issues
3. License: MIT
4. README
5. Releases