Master WebSocket Debugging with websocat: Install, Test, and Proxy

What is websocat?

websocat is a Rust‑written command‑line utility for the WebSocket protocol, inspired by netcat, socat and curl. It provides a lightweight way to open, test and proxy WebSocket connections.

Installation

Package managers

macOS (Homebrew): brew install websocat
FreeBSD: pkg install websocat

Pre‑compiled binaries

Download the appropriate binary from the GitHub releases page (https://github.com/vi/websocat/releases), extract and run.

Build from source

cargo install websocat

Typical usage examples

Echo test

websocat ws://echo.websocket.org

Type any text; the server echoes it back. Press Ctrl‑D to exit.

Local WebSocket server

websocat -s 8080
# Listening on ws://127.0.0.1:8080/

Connect from another terminal: websocat ws://127.0.0.1:8080/ Multiple clients see each other's messages, forming a simple chat.

Bidirectional TCP ↔ WebSocket proxy

websocat --oneshot -b ws-l:127.0.0.1:1234 tcp:127.0.0.1:22

Wrap SSH traffic in WebSocket, useful for firewall traversal or web‑app integration.

Broadcast to all connected clients

websocat -t ws-l:127.0.0.1:1234 broadcast:mirror:

All clients receive each other's messages.

Secure WebSocket (WSS)

websocat wss://example.com

Skip certificate verification (development only)

websocat -k wss://localhost:8443

Advanced options

Traffic monitoring: prefix the address with log: to see protocol details.

Performance tuning: --async-stdio improves I/O efficiency; -B adjusts buffer size.

Auto‑reconnect: autoreconnect automatically restores broken connections.

JSON‑RPC: communicate with Chrome DevTools protocol, e.g.:

echo '{"id":1,"method":"Page.navigate","params":{"url":"https://example.com"}}' |
websocat --jsonrpc ws://127.0.0.1:9222/devtools/page/XXX

Compression: websocat can use deflate, gzip or zlib to reduce bandwidth.

System integration

Run as a systemd service with socket activation for on‑demand startup.

Example Nginx reverse‑proxy configuration forwarding /ws to a local websocat instance:

location /mywebsocket {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}