# whistle: A Node.js Debugging Proxy for HTTP, HTTPS, HTTP/2, and WebSocket Traffic

> whistle is a cross-platform network debugging proxy built on Node.js that captures and modifies HTTP, HTTPS, HTTP/2, WebSocket, and TCP traffic through a rule-based configuration system. It ships with a web UI and built-in tools for remote DOM inspection, console log viewing, and request replay.

**avwo/whistle** — HTTP, HTTP2, HTTPS, Websocket debugging proxy

- Repository: https://github.com/avwo/whistle
- Website: https://wproxy.org/
- Stars: 15,707 · Forks: 1,179
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/avwo-whistle

## What whistle Solves and Who It Is For

whistle is a Node.js debugging proxy released under the MIT license. It captures and modifies network traffic across HTTP, HTTPS, HTTP/2, WebSocket, and TCP, all from a single tool. The package.json lists it as both a fiddler-alternative and a charles-alternative, placing it in the category of man-in-the-middle debugging proxies normally associated with those commercial tools.

The intended audience is web and mobile developers who need to inspect or rewrite traffic between a client application and a server. This includes debugging API responses on a mobile device, overriding API responses for local testing, injecting scripts into web pages, or watching WebSocket frames in real time. whistle handles all of these through a text-based rule system configured in the web UI.

whistle also targets teams running in headless server environments. The README specifically documents a four-step setup for Linux servers without a desktop environment, making it usable in CI pipelines or remote debugging scenarios where a GUI application is not an option.

## How whistle Intercepts and Modifies Traffic

whistle operates as a standard HTTP/HTTPS forward proxy. Applications route their traffic through whistle's proxy address, and whistle decrypts HTTPS connections using a self-signed root certificate it generates and installs on the host. This is a man-in-the-middle approach: whistle terminates the TLS connection from the client, inspects or modifies the request, and establishes a new TLS connection to the upstream server.

The proxy listens on port 8899 by default, as specified in package.json. The web management interface is served at the local hostname local.whistlejs.com on the same port. The data storage directory is named .whistle and sits in the user's home directory.

Rule-based configuration is the central mechanism for modifying traffic. Rules are written as lines of text in the whistle UI and define patterns and actions: match a URL pattern, then apply an action such as redirecting to a different host, injecting a response body, adding headers, or delaying the response. The README describes this as configuration by rule rather than code.

whistle supports four proxy modes in addition to the standard HTTP forward proxy: HTTPS proxy, SOCKS proxy, reverse proxy, and a mode where it can be embedded as an npm module. The npm module mode lets a project embed whistle programmatically, which is useful for integration testing or CLI tooling that needs traffic inspection without a separate proxy process.

The package.json specifies a socket limit of 256 and a timeout of 360,000 milliseconds (six minutes) per connection.

## Installing whistle and Starting the Proxy

Desktop users on macOS, Windows, or Linux can use the whistle client application at github.com/avwo/whistle-client, which the README describes as avoiding most manual installation steps.

For headless Linux servers or users who prefer the npm route, the README gives four steps. Install whistle globally via npm:

```bash
npm i -g whistle
```

whistle is also available via Homebrew:

```bash
brew install whistle
```

Once installed, start the proxy:

```bash
w2 start
```

For HTTPS inspection, install the root certificate that whistle uses to decrypt TLS traffic:

```bash
w2 ca
```

The README notes that on Windows the installer shows a prompt where the user must select yes, and on macOS a system password or Touch ID confirmation may be required.

To route the system's traffic through whistle, set the system proxy:

```bash
w2 proxy
```

To point at a specific proxy address instead:

```bash
w2 proxy "10.x.x.x:8888"
```

To disable the system proxy:

```bash
w2 proxy 0
```

The full set of management commands covers stop (w2 stop), restart (w2 restart), and status (w2 status). These control the whistle daemon process. The CLI binary is registered under three names: whistle, w2, and wproxy, all pointing to the same entry point in bin/whistle.js.

## Built-In Debugging Tools: Weinre, Console, and Composer

whistle bundles three debugging tools in its web UI that go beyond basic traffic capture.

Weinre provides remote DOM inspection. The README describes it as a tool for remote DOM checking (远程DOM检查). Weinre works by injecting a script into a page that connects back to the Weinre server; the developer then inspects the live DOM from whistle's UI without needing native browser developer tools on the target device.

The Console tool captures JavaScript console output from pages running on the device being proxied. This is useful for debugging mobile web views or embedded browsers where the device does not expose developer tools directly.

Composer supports request replay and editing. A captured request can be opened in Composer, its headers, body, and URL modified, and then resent. This replaces the need to reproduce a specific request manually through a client application.

All three tools are accessible from the centralized whistle management interface alongside traffic capture, rule configuration, and plugin management. The README describes this as a one-stop management interface.

The weinre2 package is listed as a runtime dependency in package.json at version 1.3.6. The dependency is bundled with whistle rather than requiring a separate Weinre installation.

## whistle Versus Charles and Fiddler

The package.json keywords list both fiddler-alternative and charles-alternative, which are the two most widely known commercial HTTP debugging proxies. The practical differences visible from the repository are several.

whistle is MIT-licensed and runs entirely on Node.js. Charles is a commercial Java application that requires a paid license for use beyond a trial period. Fiddler is a commercial Windows-native application with a free tier that has feature limitations. Because whistle runs on Node.js, it has no native GUI of its own; the web UI at local.whistlejs.com:8899 is the entire interface.

Charles and Fiddler both provide native application installers on their respective platforms. whistle's installation requires Node.js to be present; the README covers npm and Homebrew as the two supported paths. The whistle-client project at github.com/avwo/whistle-client offers a desktop wrapper, but the core tool is a Node.js daemon.

For teams that are already running a Node.js-heavy stack and want an open-source, MIT-licensed tool with plugin extensibility and headless Linux support, whistle fits without adding a commercial dependency. Teams that need a self-contained native application, certificate management GUI, or commercial support should evaluate Charles or Fiddler instead.

## Plugin System and Limitations

whistle supports plugins that extend both the rule system and the management UI. Plugins can define new rule types and add new panels to the web interface. The README describes this as extensibility for rules and interface functionality (扩展规则与界面功能). Plugins are separate npm packages; the README does not document the plugin API.

Several limitations are documented in the README. First, HTTPS inspection requires a root CA installation on every device that routes traffic through whistle. On managed corporate devices this may require IT approval; the README does not document a way to skip this step and still inspect HTTPS traffic.

Second, the README does not document certificate pinning bypass. Applications that implement certificate pinning will refuse whistle's certificate and show connection errors rather than passing traffic through the proxy. This is a well-known limitation of MITM proxies in general, and the README is silent on whether whistle provides tooling to address it.

Third, whistle has no GitHub releases. Version 2.10.10 is the current version as shown in package.json; release history is tracked in CHANGELOG.md and CHANGELOG-en_US.md in the repository.

The last push was on 2026-09-21, indicating recent activity on the repository.

## Conclusion

whistle is for developers who need to inspect and modify HTTP, HTTPS, HTTP/2, WebSocket, and TCP traffic on macOS, Windows, or Linux, and who want a rule-based configuration approach with a browser-based UI rather than a native GUI application. It is the wrong tool for developers who need to avoid a Node.js runtime dependency or who need a licensed commercial support contract; Charles and Fiddler, named as alternatives in the package.json keywords, are commercial options. Before relying on whistle for HTTPS inspection, verify that the root certificate installation step (w2 ca) completes successfully on the target operating system, since the README notes macOS may require a password or Touch ID prompt and Windows requires a manual confirmation.

## FAQ

### How do I install and start whistle?

Install whistle globally with npm i -g whistle (or brew install whistle on macOS), then start the daemon with w2 start. The web UI is accessible at local.whistlejs.com on port 8899 by default.

### What is the default port whistle runs on?

whistle listens on port 8899 by default, as specified in package.json. The web management interface and the proxy port share the same value.

### Does whistle support HTTPS traffic inspection?

Yes; whistle decrypts HTTPS traffic using a self-signed root certificate. Run w2 ca to install the certificate, then confirm the system prompt (Windows requires selecting yes, macOS may require a password or Touch ID). Without this step, HTTPS connections pass through without inspection.

## Sources

- [avwo/whistle on GitHub](https://github.com/avwo/whistle)
- [Issues](https://github.com/avwo/whistle/issues)
- [License: MIT](https://github.com/avwo/whistle/blob/master/LICENSE)
- [Project website](https://wproxy.org/)
- [README](https://github.com/avwo/whistle/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/avwo-whistle