# Whistle — HTTP, HTTPS & WebSocket Debugging Proxy

> Whistle is an open-source, cross-platform HTTP/HTTPS/WebSocket debugging proxy built with Node.js that lets developers inspect, modify, and mock network traffic with a powerful rule system.

## Install

Save in your project root:

# Whistle — HTTP/HTTPS/WebSocket Debugging Proxy

## Quick Use
```bash
npm install -g whistle
w2 start
# Open http://127.0.0.1:8899 in your browser
```

## Introduction
Whistle is a Node.js-based network debugging tool that acts as a proxy between your application and the network. It enables developers to capture, inspect, replay, and modify HTTP/HTTPS/WebSocket traffic using a flexible rules-based configuration, replacing heavier tools like Charles or Fiddler.

## What Whistle Does
- Captures and displays HTTP, HTTPS, and WebSocket traffic in real time
- Modifies request and response headers, bodies, and status codes on the fly
- Maps remote resources to local files for rapid frontend development
- Provides a web-based UI accessible from any browser at the proxy address
- Supports custom plugins to extend capture, rules, and UI panels

## Architecture Overview
Whistle runs as a local Node.js proxy server. It intercepts traffic by sitting between the client and the target server, using MITM for HTTPS decryption when a root CA is installed. The rules engine evaluates pattern-based directives that can rewrite URLs, inject headers, throttle bandwidth, or serve mock responses. A built-in web dashboard renders traffic logs and rule editors.

## Self-Hosting & Configuration
- Install globally via npm; no build step required
- Configure your browser or system proxy to point to Whistle's port (default 8899)
- Install the root CA certificate for HTTPS inspection
- Write rules in a simple DSL: patterns on the left, actions on the right
- Supports multi-user mode with authentication for shared team proxies

## Key Features
- Pattern-based rules engine for URL rewriting, mocking, and header injection
- HTTPS decryption via auto-generated root CA certificates
- WebSocket frame inspection and modification
- Built-in Weinre integration for remote mobile debugging
- Plugin architecture with community extensions

## Comparison with Similar Tools
- **Charles Proxy** — proprietary, paid license; Whistle is free and open source
- **Fiddler** — Windows-centric; Whistle is cross-platform via Node.js
- **mitmproxy** — Python-based with CLI focus; Whistle has a web UI and simpler rule syntax
- **Proxyman** — macOS-only, paid; Whistle runs everywhere Node.js does
- **Lightproxy** — built on top of Whistle with an Electron wrapper

## FAQ
**Q: Does Whistle support HTTPS traffic?**
A: Yes. Install the auto-generated root CA certificate and Whistle decrypts HTTPS traffic transparently.

**Q: Can I use Whistle to mock API responses?**
A: Yes. Use file, tpl, or statusCode rules to return custom responses without hitting the real server.

**Q: Does it work on mobile devices?**
A: Yes. Point your phone's Wi-Fi proxy to Whistle's IP and port. Use the built-in Weinre panel for DOM inspection.

**Q: How do I write rules?**
A: Rules follow a simple pattern: `match-pattern  operator://value`. For example, `example.com/api  file:///mock/data.json`.

## Sources
- https://github.com/avwo/whistle
- https://wproxy.org/whistle/

---
Source: https://tokrepo.com/en/workflows/asset-41b3ce43
Author: AI Open Source