websocat: Bridging WebSockets and Traditional Sockets

Table of Contents#

• What is websocat?
• Installation
• Basic Usage
• Advanced Features
• Common Use Cases
• Best Practices
• Troubleshooting
• Under the Hood (Brief)
• Alternatives Comparison
• Frequently Asked Questions (FAQ)
• Conclusion
• References

What is websocat?#

websocat is an open-source (MIT-licensed) tool that forwards data bidirectionally between:

• WebSocket endpoints (ws://, wss://).
• Traditional sockets (TCP, Unix domain sockets).
• Standard input/output (stdin/stdout).

Core Roles#

1. Client: Connect to a WebSocket server and forward data to/from a local socket (or stdin/stdout).
2. Server: Expose a WebSocket endpoint that forwards data to/from a target socket (TCP, Unix, or another WebSocket).
3. Proxy/Bridge: Act as a transparent bridge between any two endpoints, including WebSocket-to-TCP, WebSocket-to-Unix socket, and more.

Key Features#

• Text and binary modes with automatic line-to-message conversion
• Auto-reconnect and connection-reuse modes
• Broadcast mode (send messages to all connected clients)
• SOCKS5 proxy support
• JSON-RPC formatting for API testing
• TLS/SSL encryption for both client and server
• Compression (deflate, gzip, zlib)
• Prometheus metrics export

Installation#

websocat is written in Rust. Install via:

Linux#

• Debian/Ubuntu: Download the pre-compiled binary from the GitHub releases or install via Cargo: cargo install websocat.
• Fedora (via COPR):

  sudo dnf copr enable atim/websocat -y
  sudo dnf install websocat

• Arch Linux:

  sudo pacman -S websocat

• Cargo (Rust):

  cargo install websocat

Windows#

• Scoop:

  scoop install websocat

• Binary: Download from GitHub releases and add to PATH.

macOS#

• Homebrew:

  brew install websocat

• Cargo (Rust):

  cargo install websocat

FreeBSD#

pkg install websocat

Docker#

docker run --rm -ti ghcr.io/vi/websocat:nightly ws://ws.vi-server.org/mirror

Basic Usage#

websocat uses the syntax:

websocat [OPTIONS] <source> <destination>

where source/destination are endpoints (WebSocket, TCP, Unix, or stdio).

For interactive use, consider pairing with rlwrap for readline support (line editing, history):

rlwrap websocat ws://ws.vi-server.org/mirror

1. Connect to a WebSocket Server (Client Mode)#

Test a public WebSocket echo server:

websocat ws://ws.vi-server.org/mirror -

Type text and press Enter—the server echoes it back.

2. Serve a WebSocket Endpoint (Server Mode)#

The simplest way to start a WebSocket server is with the -s flag:

websocat -s 8080

This listens on ws://127.0.0.1:8080/ and echoes back any messages received.

For more control, use the advanced syntax to specify endpoints:

websocat ws-l:127.0.0.1:8080 -

Connect to it from another terminal:

websocat ws://127.0.0.1:8080 -

3. Bridge WebSocket to a TCP Socket#

Forward a WebSocket connection to a local TCP server (e.g., 127.0.0.1:9090):

websocat ws-l:127.0.0.1:8080 tcp:127.0.0.1:9090

• ws-l:127.0.0.1:8080: Listen for WebSocket connections.
• tcp:127.0.0.1:9090: Forward data to the TCP server.

4. TLS-Encrypted WebSockets (wss)#

Connect to a secure WebSocket server:

websocat wss://example.com:443 -

Serve a secure WebSocket (with PEM format certificate and private key):

websocat --tls-certificate cert.pem --tls-private-key key.pem wss-l:0.0.0.0:8443 -

(Use --insecure to skip TLS verification for local testing only.)

Advanced Features#

Unix Domain Sockets#

Forward a WebSocket to a Unix socket (e.g., /tmp/my.sock):

websocat ws://localhost:8080 unix-connect:/tmp/my.sock

Serve a WebSocket that forwards to a Unix socket:

websocat ws-l:127.0.0.1:8080 unix-connect:/tmp/my.sock

Timeouts & Keepalive#

• Handshake Timeout: Wait 5s for a handshake:

  websocat --ws-handshake-timeout 5 ws://example.com -

• Ping Interval: Send WebSocket pings every 30s (keep connection alive):

  websocat --ping-interval 30 ws://example.com -

Scripting with Stdio#

Use stdin/stdout as a socket (e.g., pipe text to a WebSocket):

echo "Hello" | websocat ws://ws.vi-server.org/mirror -

Send a file to a WebSocket:

websocat ws://ws.vi-server.org/mirror - < message.txt

Auto-Reconnect#

For unstable connections, use autoreconnect: to automatically restore connectivity:

websocat autoreconnect:ws://unstable-server.example.com/data

Broadcast Mode#

Set up a WebSocket server that broadcasts messages to all connected clients:

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

Open multiple terminals and connect with websocat ws://127.0.0.1:8080—any message sent by one client is shared with all others.

Common Use Cases#

1. Debugging WebSocket Servers#

Inspect traffic with -v (prints framing, bytes transferred):

websocat ws://localhost:8080 -v -

2. IoT Device Integration#

Bridge a TCP-based IoT device to a WebSocket (control via a web app):

websocat ws-l:0.0.0.0:8080 tcp:192.168.1.100:23

3. Legacy System Integration#

Integrate a legacy TCP service (e.g., mainframe app) with a web UI:

websocat ws-l:0.0.0.0:8080 tcp:10.0.0.1:5000

4. Local Development#

Test a WebSocket client against a mock TCP server (e.g., with netcat):

1. Run a TCP echo server:

   nc -l -p 9090 -k

2. Bridge WebSocket to it:

   websocat ws-l:127.0.0.1:8080 tcp:127.0.0.1:9090

Best Practices#

Security#

• TLS in Production: Always use wss:// (not ws://). Provide valid PEM format certificate and private key with --tls-certificate and --tls-private-key.
• Access Control: Bind to localhost (e.g., ws-l:127.0.0.1:8080) for internal services. For public access, use firewalls or reverse proxies (e.g., Nginx).
• Avoid --insecure in Production: This skips TLS verification—only use it for local testing.

Performance#

• Text vs. Binary Mode: Use --text (default) for UTF-8 text, --binary for raw binary data (e.g., protobuf).
• Resource Limits: Monitor CPU/memory for high-traffic scenarios; scale horizontally (e.g., multiple instances behind a load balancer).

Error Handling#

• Verbose Logging: Use -v to diagnose issues (framing errors, connection drops).
• Retry Mechanisms: Implement client-side retries (e.g., in a shell script):

  until websocat ws://example.com -; do sleep 1; done

Troubleshooting#

1. Connection Refused#

• Check if the target server (WebSocket/TCP) is running.
• Verify IP/port (e.g., 127.0.0.1 vs. 0.0.0.0).
• Check firewalls (e.g., ufw, iptables).

2. Protocol Mismatch#

• Ensure both ends use the same mode (--text/--binary).
• Verify WebSocket version (websocat supports RFC 6455).

3. TLS Errors#

• Invalid certs: Ensure the SSL cert/key match the domain.
• Hostname mismatch: The certificate’s Common Name (CN) must match the server’s hostname.

4. Framing Issues#

• Use -v to check for invalid frames (e.g., malformed UTF-8 in text mode).
• Ensure the client/server handles WebSocket fragmentation (websocat does this by default).

Under the Hood (Brief)#

websocat is written in Rust and uses Tokio for asynchronous I/O, handling:

• WebSocket Framing: Parses RFC 6455 frames (opcodes, masks, payloads).
• Socket I/O: Manages TCP/Unix socket communication with non-blocking I/O.
• Async Multiplexing: Efficiently forwards data between endpoints without blocking.
• Address Type System: A flexible specifier system (ws://, tcp:, unix:, mirror:, etc.) that allows combining overlays and address types for complex routing.

Note: Websocat v1 (current stable) uses older dependency versions. A complete rewrite (Websocat4) using modern Tokio 1.x and Tungstenite is in alpha testing.

Alternatives Comparison#

websocat stands out for its comprehensive address type system, combining the simplicity of netcat with the versatility of socat, specifically designed for WebSocket protocols.

Frequently Asked Questions (FAQ)#

Is websocat still maintained?#

Yes. The latest stable release (v1.14.1) was published in December 2025. A major rewrite (Websocat4, v4.0.0-alpha3) is also in development, though v1 remains the recommended stable version.

Can websocat handle binary data?#

Yes. Use --binary (-b) mode for raw binary data (e.g., protobuf) and --text (-t) mode for UTF-8 text. websocat automatically converts between line-delimited streams and WebSocket messages.

How do I keep a WebSocket connection alive?#

Use the --ping-interval option to send periodic WebSocket pings:

websocat --ping-interval 30 ws://example.com -

Can I use websocat with a SOCKS5 proxy?#

Yes. Use the --socks5 option:

websocat --socks5 127.0.0.1:9050 ws://example.com -

Does websocat support IPv6?#

Yes. IPv6 is supported. Surround IP addresses in square brackets or use them as-is depending on context.

Conclusion#

websocat simplifies bidirectional communication between WebSockets and traditional sockets. Whether debugging, integrating legacy systems, or prototyping IoT solutions, it offers flexibility and performance. Follow best practices (security, performance tuning) and explore advanced features to unlock its full potential.

References#

• websocat GitHub Repository: https://github.com/vi/websocat
• websocat Releases (Latest v1.14.1): https://github.com/vi/websocat/releases
• websocat4 Documentation: https://websocat.net/websocat4/
• WebSocket Protocol (RFC 6455): https://datatracker.ietf.org/doc/html/rfc6455
• Rust Tokio: https://tokio.rs/
• Public Echo Server: https://ws.vi-server.org/mirror

Explore websocat’s official documentation and Websocat4 preview to discover more use cases and configurations!