中文 · English

Whistle is a powerful cross-platform network packet capture and debugging tool. This client is the official desktop version and supports the following operating systems:

• macOS（Apple Silicon / Intel）
• Windows
• Linux（Fedora / Ubuntu）

If the system you are using does not support the Whistle Client (such as a server without a graphical interface or a special device), you can use the Whistle: https://github.com/avwo/whistle

Installation

Please select the corresponding installation steps according to your operating system.

macOS

1. Select the correct installation package

Select the corresponding version according to your Mac processor type:

• Apple Silicon chip (M1/M2/M3 series) → Download ARM 64-bit version: Whistle-vx.y.z-mac-arm64.dmg
• Intel/AMD chip → Download x86_64 version: Whistle-vx.y.z-mac-x64.dmg

2. Installation steps

1. After downloading, double-click the downloaded .dmg file

2. Drag the Whistle icon to the Applications folder

   

3. If the following situations occur:

   • "Application already exists" → Select "Overwrite"

   • Unable to overwrite → Please exit the running Whistle client first

3. Security Tips

Some enterprise security software may give false positives. Suggestions:

• Select "Allow" when running for the first time

• If there is continuous interception, please contact the IT department to add Whistle to the whitelist

Windows

1. Download the installation package

Choose the appropriate version according to your permission requirements:

• [Recommended] Standard Edition (Administrator permissions required): Whistle-vx.y.z-win-x64.exe

  Supports full functionality, including pseudo-protocols (whistle://client)

• User version (no administrator privileges required): Whistle-user-installer-vx.y.z-win-x64.exe

  Functional limitations: pseudo-protocol calls are not supported

2. Run the installer

After double-clicking the downloaded installation package, you may see the following security prompts. Please follow the instructions in order:

1. User Account Control prompt → Click "Yes" to continue the installation

2. Installation wizard interface → Follow the prompts to complete step by step

Linux (Fedora/Ubuntu)

This client currently supports two Linux distributions: Fedora and Ubuntu.

Download the installation package:

• Intel/AMD 64-bit (x86_64): Whistle-vx.y.z-linux-x86_64.AppImage
• ARM 64-bit (arm64): Whistle-vx.y.z-linux-arm64.AppImage

Installation method reference: https://itsfoss.com/cant-run-appimage-ubuntu/

Usage

Start the client

After installation, please start it in the following way:

1. Click the Whistle icon on the desktop
2. Or find Whistle through the system application menu

After starting, please follow the steps below to complete the necessary initial settings (must be done when running for the first time):

1. Open the Whistle menu item at the top of the client
2. Click Install Root CA: Install the system root certificate for parsing HTTPS Request
3. Enable Set As System Proxy: Set the system proxy to capture the system's web requests

Top menu

1. Proxy Settings: See Proxy Settings below
2. Install Root CA: Install the root certificate
3. Check Update: Check if there is a new version
4. Set As System Proxy: Set the system proxy
5. Start At Login: Whether to automatically start the Whistle client at startup
6. Restart: Restart the client
7. Quit: Exit the client

Proxy Settings

1. Proxy Port: Required, proxy port, default is 8888

2. Socks Port: Add Socksv5 proxy port

3. Bound Host: Specify the listening network card

4. Proxy Auth: Set the username and password to authenticate the request through the proxy

5. Bypass List: Whitelist domain name that is not proxied, supports the following three formats:

   • IP: 127.0.0.1
   • Domain name: www.test.com
   • Wildcard: *.test.com (this includes all sub-domains of test.com)

6. Use whistle's default storage directory: The directory that stores whether to switch back to the command line version, so that the previous configuration data can be retained (after checking, the command line version must be stopped, otherwise the configuration may overwrite each other)

Install plugins

1. Click the Plugins tab in the left navigation bar

2. Click the Install button at the top

3. Enter the plugin name in the pop-up window (supports installing multiple plugins at the same time):

   • Multiple plugins are separated by spaces or line breaks

   • Custom npm mirror sources can be specified:

     • Directly add --registry=mirror address after the plugin name

     • Or select a mirror source that has been used in the past from the drop-down list

Example:

w2 install whistle.script whistle.inspect

FAQ

1. Enable the client to set the system proxy. Some applications (such as Outlook, Word, etc.) may have network connection exceptions

Check whether there is the following captureError exception request in the packet capture interface:

Configure the domain name with such exceptions to the Bypass List rule of Proxy Settings:

2. How to update the client?

• Check for new versions: Click the Whistle menu in the upper left corner → Check Update → Follow the prompts to complete the update

• Manually download updates: Visit GitHub Releases to download the latest version and reinstall according to the above document

3. How to synchronize previous data?

By default, the Whistle client uses an independent storage directory. If you want to continue using the directory of the command line version, you can switch back to the default directory of the command line through Use whistle's default storage directory in Proxy Settings:

Note: Only a single Whistle instance should access this directory simultaneously. Running multiple instances concurrently will lead to configuration conflicts and data corruption!

Quick Start

See the official guide for usage and examples: https://wproxy.org/docs/getting-started.html

License

MIT — see the LICENSE file