Wirescry

A desktop tool for seeing, debugging and rewriting HTTP traffic. Built with Electron, TypeScript and React, with Mockttp as the proxy engine.

This is an early Stage 1 skeleton. See FEATURES.md for the full plan.

Requirements

• Node.js 22.12 or later (tested with Node 26 and npm 11)
• macOS, Windows or Linux

Install

npm install

Electron downloads its binary the first time it runs, so the first npm run dev takes a little longer.

Run

npm run dev

This opens the Wirescry window with hot reload. The toolbar shows the proxy port (usually 8000), and requests appear in the list as they pass through.

The list stays fast with thousands of requests and keeps the most recent 10,000. Search with Cmd/Ctrl+F, narrow it with the quick filters (JSON, HTML, gRPC, Errors and so on) or field filters in the search box such as status>=400, status=5xx, method=POST, host=api.*, path~login, size>1mb, time>500ms, grpc=NOT_FOUND or -host=*.google.com (the ? button lists them), and use Pause recording to let traffic through without recording it. Click a request, or use the arrow keys, to see its headers and bodies.

To send traffic through it:

• Chrome, Chromium, Edge or Brave: click Launch to open the browser with a fresh temporary profile that uses the proxy and trusts Wirescry's certificate. The profile is deleted when the browser closes.

• Firefox: Firefox can't be told to trust a certificate from the command line, so Wirescry keeps its own Firefox profile in the user data folder. The first launch opens a setup page at http://wirescry.internal/ (answered by the proxy itself) where you trust the certificate once. Later launches go straight to browsing.

• Terminals: Setup → Terminals opens Terminal or iTerm (macOS), PowerShell or Command Prompt (Windows), or your terminal (Linux) with variables that send Node.js, Python, Ruby, Go, PHP, Java, curl and git through Wirescry. The same variables are shown for bash, zsh, fish, PowerShell and cmd, to paste into a terminal that's already open. They point tools at a CA bundle (ca-bundle.pem in the user data folder) holding Wirescry's CA plus the usual public and system roots. Java gets JAVA_TOOL_OPTIONS with proxy settings and a JKS trust store holding the same certificates (Java can't read PEM bundles). PHP gets an extra .ini (through PHP_INI_SCAN_DIR) that points its curl and OpenSSL settings at the bundle. On Windows, curl.exe ignores CURL_CA_BUNDLE, so terminals there point CURL_HOME at a Wirescry curl config that sets the CA and turns off revocation checks (a local CA has nowhere to publish revocation lists); your own _curlrc isn't read in those terminals. Known gaps: the Python and Ruby built into macOS ignore the certificate setting, and Go on Windows reads only the Windows certificate store.

• Anything else: the Setup view shows the proxy address and a Save certificate… button.

• curl:

  curl --proxy http://127.0.0.1:8000 --cacert "$HOME/Library/Application Support/Wirescry/ca.pem" https://example.com/
  

  On Linux the certificate is in ~/.config/Wirescry/ca.pem, and on Windows in %APPDATA%\Wirescry\ca.pem.

The Setup view also lets you fix the proxy port (it's otherwise picked automatically, starting at 8000) and reset the certificate, which creates a new one and removes the Firefox profile.

npm start runs the production build without packaging it.

When requests fail

If the real server can't be reached, the request's Status shows why: DNS, Refused, TLS, Timeout, Reset, No route, or Closed (the client gave up first). The detail pane explains the problem in plain language, with the original error. The client receives a 502 from Wirescry in these cases. Wirescry doesn't impose its own response timeout, so long-polling and other slow responses keep working; a request still waiting just shows ….

WebSocket connections show in the list with status 101 and type websocket. Select one to see its messages live: direction, time since the connection opened, size and content, with JSON formatted and binary shown as hex. Filter by sent or received, or search the text. Messages are kept in memory, at most 64 KB of each and 64 MB in total; the oldest are dropped first, and the view says when.

Logs

Errors and warnings from the window, the backend and the UI are written to wirescry.log (Help → Show Log File):

• macOS: ~/Library/Logs/Wirescry/
• Windows: %APPDATA%\Wirescry\logs\
• Linux: ~/.config/Wirescry/logs/

The file is readable only by you, starts over past 5 MB (keeping one previous file), and never contains the API token. It does include hostnames of requests that failed.

Test and check

npm test

The backend's tests again, under Electron's own Node, which the app runs on. It uses BoringSSL rather than OpenSSL, so TLS errors differ:

npm run test:electron

npm run lint

npm run typecheck

npm run format:check

The backend tests start the real proxy and API, push an HTTPS request through the proxy to a local server, and check that it streams to an API client. They also check that the API rejects a missing or wrong token, other origins and non-loopback hosts.

Package

npm run package

Builds unsigned installers for the current platform into release/. Use package:mac, package:win or package:linux for a specific one.

Signed releases, notarization and auto-update are handled by the release workflow; see docs/RELEASING.md.

Plugins and Pro

Pro features live in a separate, private repo (wirescry-pro) and plug into the app through src/plugin-api:

This is the beginning of the README. Read the rest at the original. Read the full README ↗