websocat operates by creating two connections and exchanging data between them. It supports three primary modes of invocation:

1. Simple client mode: Connects to a remote WebSocket server.
2. Simple server mode: Starts a local WebSocket server.
3. Advanced [socat]-like mode: Uses address specifiers to bridge different types of connections (e.g., bridging a local TCP port to a WebSocket mirror).

If one connection is bytestream-oriented (like terminal stdin/stdout or a TCP connection) and the other is message-oriented (like WebSocket or UDP), websocat defaults to operating in lines, where each line corresponds to a single message. This behavior can be configured via specific options.

In Accept=no mode, websocat is socket-activated by systemd and remains running to listen for multiple connections. This requires the --accept-from-fd option. Note that this mode currently does not work with TCP sockets (use Unix sockets instead).

# /etc/systemd/system/qqq.socket
[Unit]
Description="websocat"

[Socket]
ListenStream=/run/qqq.socket
Accept=no

[Install]
WantedBy=sockets.target

# /etc/systemd/system/qqq.service
[Unit]
Description="websocat"
Requires=qqq.socket

[Service]
ExecStart=/opt/websocat -E -b --accept-from-fd l-ws-unix:3 tcp:127.0.0.1:22

[Install]
WantedBy=multi-user.target

Example SSH client command to use this setup:

ssh root@localhost -o 'ProxyCommand=/opt/websocat -E -b - ws-c:unix:/run/qqq.socket'

To inspect traffic passing through websocat, use the log: filter overlay. This allows you to view data at different layers of the protocol stack.

• Message level: Shows individual WRITE and READ operations.
• Protocol level: Shows raw HTTP/WebSocket handshake and frame data.

In Accept=yes mode, each incoming client connection triggers a separate websocat process. This is achieved by using a systemd socket unit with Accept=yes and a template service unit (using the @ character).

# /etc/systemd/system/qqq.socket
[Unit]
Description="websocat"

[Socket]
ListenStream=/run/qqq.socket
Accept=yes

[Install]
WantedBy=sockets.target

# /etc/systemd/system/qqq@.service
[Unit]
Description="websocat"
Requires=qqq.socket

[Service]
Type=simple
ExecStart=/opt/websocat -E -b ws-inetd: tcp:127.0.0.1:22
StandardInput=socket
NonBlocking=true

[Install]
WantedBy=multi-user.target

You can install websocat using pre-built binaries or by building from source.

Pre-built binaries

Download binaries for Linux (usual and musl), Windows, OS X, and Android from the releases page.

Building from source

1. Install the Rust toolchain.
2. Run cargo build --release.
3. The executable will be located in target/release/websocat.

Note on Rust versions:

• For websocat v1.9 - 1.11, use Rust 1.46 to 1.63.
• For websocat v1.6 - 1.8, use Rust 1.34 to 1.63.
• Building with legacy Rust versions (e.g., 1.46) may require manually copying Cargo.lock.legacy to Cargo.lock before building.

When using Nginx as a reverse proxy for WebSockets, a standard proxy_pass is insufficient. You must explicitly set the Upgrade and Connection headers and increase timeouts.

location /mywebsocket {
    proxy_read_timeout 1d;
    proxy_send_timeout 1d;
    proxy_pass http://localhost:8123;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

If you have the Rust toolchain installed, you can install websocat directly via cargo.

If you encounter errors related to -sys crates during installation, try using the --no-default-features flag.

To run a secure WebSocket server for development, you can use a PKCS#12 certificate file with the --pkcs12-der option.

First, generate a certificate and key using openssl, then export them to a .pkcs12 file. Finally, start websocat listening on a port with that certificate.

To connect to a secure WebSocket (wss://) without verifying the SSL certificate, use the -k option.

If your version of websocat does not support SSL or the -k flag, you can use external tools like socat or openssl s_client via the ws-c:cmd: specifier to provide the SSL layer.

Choose the installation method based on your operating system:

• FreeBSD: Use pkg install websocat.
• Debian / Ubuntu: Download pre-built executables from the GitHub releases page.
• macOS: Use Homebrew (brew install websocat) or MacPorts (sudo port install websocat).

websocat operates in three primary modes based on the number of arguments provided:

1. Simple Client Mode: Provide a single WebSocket URL to connect to. websocat ws://URL

2. Simple Server Mode: Use the -s flag followed by a port or address:port to start a WebSocket server. websocat -s 8080

3. Advanced Mode: Provide two addresses (addr1 and addr2) to bridge or proxy data between them. websocat [FLAGS] [OPTIONS] <addr1> <addr2>

Examples:

• WebSocket-to-TCP proxy: websocat --binary ws-l:127.0.0.1:8080 tcp:127.0.0.1:5678

websocat ws://ws.vi-server.org/mirror/
websocat -s 8080
websocat --binary ws-l:127.0.0.1:8080 tcp:127.0.0.1:5678

When using wss:// on Android, SSL connections may fail. To resolve this, download a certificate bundle (e.g., from https://curl.haxx.se/ca/cacert.pem) and specify it using the SSL_CERT_FILE environment variable, or use the --insecure flag.

Example using a certificate bundle

SSL_CERT_FILE=cacert.pem /data/local/tmp/websocat wss://echo.websocket.org