Self-Hosted WebSocket Proxies: Whistle vs Proxyee vs WebSocketProxy

WebSocket technology enables persistent, bidirectional communication between clients and servers — essential for real-time chat, live dashboards, collaborative editing, gaming, and IoT telemetry. As WebSocket adoption grows, the need for dedicated WebSocket proxying infrastructure becomes critical.

Most traditional reverse proxies (Nginx, HAProxy, Caddy) support WebSocket passthrough, but dedicated WebSocket proxies offer specialized features: traffic inspection, MITM debugging, protocol transformation, real-time rule-based interception, and multi-protocol support (HTTP/HTTPS/WebSocket/SOCKS).

What Is a WebSocket Proxy?

A WebSocket proxy sits between clients and WebSocket servers, intercepting and forwarding WebSocket frames. Unlike a standard HTTP reverse proxy that simply upgrades connections, a dedicated WebSocket proxy can:

• Inspect and modify frames in real-time (debugging, filtering, transformation)
• Handle multiple protocols on the same port (HTTP, HTTPS, WebSocket, SOCKS)
• Provide MITM capabilities for debugging encrypted WebSocket traffic
• Apply rule-based routing based on WebSocket URL patterns, headers, or payload content
• Log and record WebSocket sessions for compliance and troubleshooting

Comparison Overview

Whistle

Whistle is the most popular open-source WebSocket and HTTP debugging proxy. Created by avwo (a Tencent developer), it has become the go-to tool for frontend developers and QA engineers who need to intercept, modify, and debug WebSocket traffic in real-time.

Key Features

• Multi-protocol support: HTTP, HTTPS, HTTP/2, WebSocket, SOCKS5
• Built-in MITM: Intercept and inspect encrypted traffic with generated certificates
• Rule-based interception: JavaScript-based rules for request/response modification
• Plugin ecosystem: Extensible via npm packages (whistle.xproxy, whistle.inspect, etc.)
• Web dashboard: Full UI for managing rules, viewing traffic, and configuring settings
• WebSocket inspection: Real-time frame viewing, filtering, and replay
• Cross-platform: Runs on Windows, macOS, and Linux

Docker Compose Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

version: "3.8"
services:
  whistle:
    image: node:20-alpine
    container_name: whistle
    restart: unless-stopped
    ports:
      - "8899:8899"
    volumes:
      - whistle-data:/root/.whistle
    command: >
      sh -c "npm install -g whistle &&
             w2 start --port 8899 --host 0.0.0.0"
    networks:
      - proxy-net

networks:
  proxy-net:
    driver: bridge

volumes:
  whistle-data:

Configuration and Rules

Whistle uses a rule-based configuration system. Rules are defined in the web UI and support pattern matching:

1
2
3
4
5
6
7
8

# Map production WebSocket to local dev server
wss://api.example.com/socket 127.0.0.1:3000

# Inject custom headers for WebSocket upgrades
wss://api.example.com/ reqHeaders://{"X-Debug": "true"}

# Log all WebSocket frames to file
wss://api.example.com/ resBody://{log-file}

Installation

1
2
3
4
5
6
7

# Install via npm
npm install -g whistle

# Start the proxy
w2 start --port 8899

# Access the web UI at http://localhost:8899

Proxyee

Proxyee is a Java-based HTTP/HTTPS/WebSocket proxy with a focus on MITM capabilities and traffic interception. It provides a clean web interface for managing proxy rules and inspecting intercepted traffic in real-time.

Key Features

• Full MITM support: Generate and manage CA certificates for traffic inspection
• WebSocket interception: View and modify WebSocket frames in real-time
• Java ecosystem: Easy integration with existing Java infrastructure
• Web management UI: Browser-based interface for rule configuration and traffic monitoring
• HTTPS decryption: Full TLS interception with certificate management
• Tamper capabilities: Modify requests and responses on the fly

Docker Compose Deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

version: "3.8"
services:
  proxyee:
    image: openjdk:17-jdk-slim
    container_name: proxyee
    restart: unless-stopped
    ports:
      - "9090:9090"
      - "8088:8088"
    volumes:
      - ./proxyee.jar:/app/proxyee.jar
      - proxyee-data:/data
    command: java -jar /app/proxyee.jar --port 9090
    networks:
      - proxy-net

networks:
  proxy-net:
    driver: bridge

volumes:
  proxyee-data:

Usage

1
2
3
4
5
6
7
8

# Download the latest release
curl -L -o proxyee.jar https://github.com/monkeyWie/proxyee/releases/latest/download/proxyee.jar

# Run with default settings
java -jar proxyee.jar

# Access the web UI at http://localhost:9090
# Proxy listens on port 8088 by default

WebSocketProxy (koding)

WebSocketProxy is a Go library that provides WebSocket reverse proxy functionality for Go applications. Unlike Whistle and Proxyee, it is not a standalone server — it is a building block for embedding WebSocket proxying into your own Go services.

Key Features

• Go library: Embed directly into your Go applications
• Transparent proxying: Forwards WebSocket frames without modification
• Header preservation: Maintains original request headers through the proxy
• Lightweight: Minimal overhead, designed for high-throughput scenarios
• Standard library compatible: Works with net/http and gorilla/websocket

Go Integration Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package main

import (
    "log"
    "net/http"
    "net/url"

    "github.com/koding/websocketproxy"
)

func main() {
    // Backend WebSocket server
    backend, err := url.Parse("ws://backend-service:8080/ws")
    if err != nil {
        log.Fatal(err)
    }

    // Create the proxy
    wsp := websocketproxy.NewProxy(backend)

    // Optional: Add custom header handling
    wsp.UpstreamHeaders = http.Header{
        "X-Forwarded-For": []string{"true"},
    }

    // Start the proxy server
    log.Println("WebSocket proxy listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", wsp))
}

Docker Deployment (Embedded)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

version: "3.8"
services:
  ws-proxy:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ws-proxy
    restart: unless-stopped
    ports:
      - "8080:8080"
    networks:
      - proxy-net

networks:
  proxy-net:
    driver: bridge

Dockerfile:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY main.go .
RUN CGO_ENABLED=0 go build -o ws-proxy .

FROM alpine:3.20
COPY --from=builder /app/ws-proxy /usr/local/bin/
EXPOSE 8080
CMD ["ws-proxy"]

Use Case Scenarios

Frontend Development and Debugging

Whistle is the clear winner here. Its rule engine, plugin ecosystem, and WebSocket frame inspector make it ideal for frontend developers who need to mock APIs, intercept WebSocket messages, and debug real-time communication.

Security Testing and Traffic Analysis

Proxyee excels at MITM interception for security testing. Its Java-based architecture and clean web interface make it suitable for QA teams that need to inspect encrypted WebSocket traffic and verify data integrity.

Production WebSocket Routing

WebSocketProxy is the right choice for production deployments where you need to embed WebSocket proxying into a custom Go service. It handles the low-level protocol details while you focus on business logic.

Performance and Scalability

• Whistle: Node.js single-threaded architecture limits it to ~10K concurrent WebSocket connections per instance. Horizontal scaling requires multiple instances behind a TCP load balancer.
• Proxyee: Java multi-threaded model handles ~20K concurrent connections. Higher memory footprint (~200MB baseline) but better throughput under load.
• WebSocketProxy: As a Go library, it inherits Go’s excellent concurrency model. Embed in a Go service that can handle 50K+ concurrent connections with minimal memory overhead.

Why Self-Host Your WebSocket Proxy?

Self-hosting WebSocket proxy infrastructure provides several advantages over cloud-based alternatives:

• Complete traffic visibility: Inspect every WebSocket frame without sending data through third-party servers
• Custom rule engine: Apply organization-specific routing, filtering, and transformation rules
• Cost elimination: Commercial WebSocket proxy services charge per-connection or per-message fees
• Data sovereignty: Keep real-time communication data within your network perimeter
• Low latency: Deploy the proxy on the same network as your WebSocket servers for minimal overhead
• Protocol flexibility: Support non-standard WebSocket extensions, custom subprotocols, or binary frame formats

For organizations running real-time applications (chat, gaming, live dashboards, collaborative tools), a self-hosted WebSocket proxy is essential infrastructure. For general reverse proxying needs, see our reverse proxy GUI comparison. For network-level load balancing, our TCP/L4 load balancer guide covers protocol-agnostic distribution.

FAQ

What is the difference between a WebSocket proxy and a WebSocket gateway?

A WebSocket proxy forwards WebSocket frames between client and server with optional inspection and modification. A WebSocket gateway typically adds authentication, rate limiting, message routing, and protocol translation on top of proxying. Whistle and Proxyee are proxies; you can build a gateway on top of WebSocketProxy.

Can Whistle handle WSS (secure WebSocket) connections?

Yes, Whistle supports WSS through its built-in MITM capability. Install the Whistle CA certificate on your client device, and Whistle can intercept, inspect, and forward encrypted WebSocket traffic just like it does with HTTPS.

Is Proxyee suitable for production use?

Proxyee is primarily designed for development and testing. Its MITM capabilities make it excellent for debugging and QA, but for production WebSocket routing, consider using WebSocketProxy embedded in a Go service or a dedicated reverse proxy like Nginx with WebSocket upgrade support.

How do I install the Whistle CA certificate?

After starting Whistle, visit http://127.0.0.1:8899 in your browser. Click “Root CA” in the UI to download the certificate. Install it in your system’s trust store (or browser’s certificate manager) and mark it as trusted for TLS interception.

Can WebSocketProxy handle multiple backend servers?

WebSocketProxy forwards to a single backend URL. For multi-backend load balancing, place it behind an L4 load balancer like GoBetween (covered in our TCP/L4 load balancer guide) or implement custom routing logic in your Go application.

Does Whistle support HTTP/2 over WebSocket?

Whistle supports HTTP/2 proxying and WebSocket proxying as separate features. It can proxy HTTP/2 connections and WebSocket connections independently, but HTTP/2-over-WebSocket (a niche use case) requires custom plugin development.