# websocketd — Turn Any Program into a WebSocket Server

> A small command-line tool that wraps any program that reads STDIN and writes STDOUT into a full WebSocket server. Write your backend logic in any language and websocketd handles the WebSocket protocol.

## Install

Save as a script file and run:

# websocketd — Turn Any Program into a WebSocket Server

## Quick Use
```bash
# Install (macOS)
brew install websocketd

# Wrap a simple counter script
echo '#!/bin/bash
for i in $(seq 1 10); do echo $i; sleep 1; done' > count.sh
chmod +x count.sh
websocketd --port=8080 ./count.sh
```

## Introduction
websocketd is a lightweight command-line tool that takes any program or script that uses STDIN/STDOUT and wraps it into a WebSocket server. Each incoming WebSocket connection spawns a new instance of the program. Messages from the client go to the program's STDIN and each line written to STDOUT is sent back as a WebSocket message. This lets you build real-time server applications in any programming language without a WebSocket library.

## What websocketd Does
- Spawns a new process for each WebSocket connection, mapping STDIN/STDOUT to messages
- Works with programs written in any language: Bash, Python, Ruby, Go, Perl, or compiled binaries
- Serves static HTML/JS files alongside the WebSocket endpoint for self-contained demos
- Supports origin checking, TLS termination, and configurable connection limits
- Provides CGI-style environment variables with connection metadata to the child process

## Architecture Overview
websocketd is a single Go binary. When a WebSocket client connects, websocketd forks the specified program and bridges the WebSocket frames to the process's standard streams. Each line on STDOUT becomes a text frame sent to the client. Each incoming text frame is written as a line to STDIN. When the process exits or the client disconnects, the other side is cleaned up. This inetd-like model keeps the architecture simple and language-agnostic.

## Self-Hosting & Configuration
- Download a single binary from GitHub releases or install via Homebrew
- Run with `websocketd --port=PORT ./your-program` to start serving
- Use `--staticdir=./html` to serve a web frontend alongside the WebSocket endpoint
- Enable TLS with `--ssl --sslcert=cert.pem --sslkey=key.pem`
- Set `--maxforks` to limit concurrent connections and prevent resource exhaustion

## Key Features
- Zero-dependency single binary deployment on Linux, macOS, and Windows
- Language-agnostic design lets you prototype with shell scripts and scale to compiled programs
- STDERR from child processes is logged to the server console for debugging
- Built-in static file server eliminates the need for a separate HTTP server
- Environment variables expose client IP, request path, and headers to the child process

## Comparison with Similar Tools
- **Socket.IO** — Requires a Node.js server and client library; websocketd works with any language
- **ws (Node.js)** — Library-level WebSocket support; websocketd wraps existing programs without code changes
- **Caddy websocket** — Plugin-based approach; websocketd is a standalone tool with simpler configuration
- **socat** — General-purpose relay; websocketd specifically handles WebSocket protocol framing
- **gotty** — Shares a terminal over the web; websocketd is bidirectional and program-agnostic

## FAQ
**Q: Does each client get its own process?**
A: Yes. Each WebSocket connection spawns a fresh instance of the program. State is per-connection by default.

**Q: Can I use websocketd in production?**
A: websocketd is suitable for moderate workloads. For high-connection counts, consider placing it behind a reverse proxy with connection limits.

**Q: What happens if the program crashes?**
A: The WebSocket connection is closed. The client can reconnect, which spawns a new process.

**Q: Can I send binary data?**
A: websocketd operates on text lines by default. Binary data can be base64-encoded or handled through a wrapper script.

## Sources
- https://github.com/joewalnes/websocketd
- http://websocketd.com/

---
Source: https://tokrepo.com/en/workflows/asset-4abc5ab2
Author: Script Depot