Skip to content
Get packs

Guide · Open source

How to use Whistle: install, start and debug HTTPS traffic

Updated · written with AI from the project's own documentation and checked against our catalogue data

Whistle is a free, MIT-licensed debugging proxy that sits between your browser or apps and the internet. It lets you see and change the web requests and responses that pass through it, including HTTP, HTTPS, HTTP/2 and WebSocket traffic. This guide shows you how to install it, start it, set it up for HTTPS capture and set the system proxy, so you can start inspecting traffic.

whistleavwo/whistle · ★ 15.8k · MIT

Quick start

  1. 1Install Node.js. Install Node.js, which Whistle requires, from nodejs.org.
  2. 2Install Whistle. Run the global npm install command to add Whistle to your system.
  3. 3Start Whistle. Run w2 start to launch the proxy.
  4. 4Install the root certificate. Run w2 ca and follow the prompts so HTTPS traffic can be captured.
  5. 5Set the system proxy. Run w2 proxy to point your system at Whistle, or w2 proxy 0 to turn it off.
  6. 6Add rules and inspect traffic. Use rules to modify requests and responses, then review the captured traffic in the management interface.

What Whistle does and who it is for

Whistle is a cross-platform network capture and debugging tool built on Node.js. It captures and can modify requests and responses over HTTP, HTTPS, HTTP/2 and WebSocket, and it also supports TCP capture. Changes are made through rules, and a web-based management interface brings together capture, rules, plugins and built-in tools.

It suits front-end developers who want to redirect or modify requests without changing server code, testers who need to inspect HTTPS traffic from a browser or app, and developers on servers without a graphical interface. If you only need to switch proxies in your browser, a simple proxy extension is a lighter choice.

  • Capture and modify HTTP, HTTPS, HTTP/2 and WebSocket traffic
  • Configure behaviour with rules
  • Built-in tools include Weinre (remote DOM inspection), Console and Composer (request replay and editing)
  • Extend with plugins or use it as an npm module

Install Whistle with npm

Whistle requires Node.js. Install Node.js first from nodejs.org, then install Whistle globally with npm. The README also mentions Homebrew as an alternative on macOS.

Desktop users can alternatively use the Whistle client, which the README says removes most manual installation and configuration steps.

  • Prerequisite: Node.js
  • Homebrew is also supported according to the README
npm i -g whistle

Start Whistle and check its status

Start the proxy with the start command. Once it is running, you can check its state, and stop, restart or stop it with the matching commands.

w2 start w2 status w2 restart w2 stop

Install the root certificate for HTTPS capture

To read HTTPS traffic, Whistle needs its root certificate installed on your device. Without it, HTTPS capture does not work, so this step is required for testing secure sites and apps.

The installer may ask you to confirm. On Windows you choose the confirmation option at the end, and on macOS you may need to enter your login password or use Touch ID.

w2 ca

Set the system proxy to Whistle

Point your system at Whistle with the proxy command. By default this uses the local Whistle instance. To use a specific address, pass host and port. To turn the system proxy off, use 0.

If an app cannot be pointed at a proxy directly, the README suggests Proxifier (Windows and macOS). For browsers, it recommends the ZeroOmega extension for switching between proxies, and notes that Firefox and some developer tools have their own proxy settings.

  • Use the default: w2 proxy
  • Set a specific address: w2 proxy "10.x.x.x:8888"
  • Turn off the system proxy: w2 proxy 0
w2 proxy w2 proxy "10.x.x.x:8888" w2 proxy 0

Learn rules and the management interface

Whistle changes traffic through rules. The official documentation at wproxy.org has a getting-started guide with examples, which is the best place to learn rule syntax. Whistle also offers a management interface where you can view captured traffic and manage rules and plugins.

Start with a single rule on a test page you control, confirm it applies in the captured traffic, then expand from there.

  • Official getting-started guide: https://wproxy.org/docs/getting-started.html
  • Manage capture, rules, plugins and built-in tools in one interface

What people use it for

  • Redirect a live page request to a local development build without changing server code
  • Inspect HTTPS requests sent by a browser or mobile app during testing
  • Debug a web app on a headless Linux server using only the command line
  • Replay and edit a captured request with the built-in Composer tool
  • Inspect WebSocket traffic between a page and its server

Frequently asked questions

Is Whistle free to use?

Yes. Whistle is released under the MIT licence, and its source is on GitHub. The MIT licence is permissive, and the LICENSE file in the repository has the full terms.

What do I need to install Whistle?

You need Node.js installed, then you can install Whistle with npm using the global install command. The README also lists Homebrew as an option. It runs on macOS, Windows and Linux, including servers without a graphical interface.

Why does Whistle need a root certificate?

HTTPS traffic is encrypted, so Whistle must present its own certificate to read it. You install the root certificate with w2 ca. Without it, HTTPS capture will not work.

How do I turn off the Whistle proxy?

Run w2 proxy 0 to turn off the system proxy. To stop the Whistle service itself, run w2 stop.

Can Whistle run on a Linux server without a desktop?

Yes. The README describes a headless Linux server setup using the command line: install with npm, run w2 start, install the certificate with w2 ca and set the proxy with w2 proxy.

How does Whistle compare to Fiddler, Charles Proxy, mitmproxy or Burp Suite?

These are comparable debugging proxies. Whistle is open source under MIT and runs well from the command line on servers. This guide does not benchmark them, so compare the features you need in each tool's documentation before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Whistle is a good fit for front-end developers, testers and anyone who needs to debug HTTPS traffic or run a proxy on a server without a desktop, especially if you are comfortable with Node.js and rules. If you only need to switch proxies in a browser, or you cannot install a root certificate on your device, choose a simpler tool or one of the alternatives listed above.

Install options & downloads