mrrowisp

A Wisp server written in Go, with a Node.js wrapper for spawning and load-balancing across multiple worker processes.

mrrowisp supports Wisp v1, v2, and optionally Twisp (PTY over Wisp). It includes flood protection, per-source/per-destination rate limiting, IP scoring, an egress allow/deny policy, a DNS cache, and reverse-proxy IP parsing.

Features

• Wisp v1 and v2 (enableV2) over WebSocket
• Optional Twisp (enableTwisp)
• TCP and UDP stream support (allowTCP, allowUDP)
• Hostname/port allow and block lists
• Direct IP, private IP, and loopback egress controls
• Flood protection: per-source, per-destination, SYN flood detection
• IP reputation with on-disk persistence and decay
• Bandwidth and connection rate limits per IP
• Optional password authentication
• Optional upstream HTTP/SOCKS proxy
• Reverse-proxy real-IP parsing (CF-Connecting-IP, X-Forwarded-For, ...)
• Optional static file serving alongside the /wisp endpoint

Installing

From source (Go)

Requires Go 1.25+.

go build -o mrrowisp main.go

Or build cross-platform binaries into ./bin/:

./build.sh

Docker

docker build -t mrrowisp .
docker run -p 6001:6001 -v $(pwd)/config.json:/app/config.json mrrowisp

npm / pnpm (Node.js wrapper)

pnpm install mrrowisp

Running the standalone server

./mrrowisp --config config.json

Flags:

• --config <path|json> – path to a config file or an inline JSON string
• --port <n> – override the port from config
• --allow-loopback – override allowLoopbackIPs

If no --config is supplied, the built-in defaults from wisp.DefaultConfig() are used.

See example.config.json for the full list of supported options.

Using the Node.js wrapper

The wrapper spawns one or more mrrowisp Go processes and the built-in load balancing routes incoming WebSocket upgrades across them.

import { Mrrowisp } from "mrrowisp";
import { createServer } from "node:http";

const wisp = new Mrrowisp({ port: 6001, logLevel: "info" });
await wisp.start(4); // spawn 4 workers, which would route to 6001, 6002, 6003, and 6004 or similar automatically

const server = createServer();
server.on("upgrade", (req, socket, head) => wisp.route(req, socket, head));
server.listen(8080);

API:

• new Mrrowisp(partialConfig?) – overrides merged onto defaults loaded from dist/config.json
• start(count = 1) – spawn N worker processes, each on its own port
• route(req, socket, head) – proxy a WebSocket upgrade to the next worker
• stop() – SIGTERM all workers
• kill() – SIGKILL all workers

Configuration

The full schema lives in example.config.json and wisp/config.go. Featured keys:

Key	Default	Description
port	6001	TCP port to listen on
allowTCP / allowUDP	true	Permit TCP/UDP stream types
allowDirectIP	false	Allow connecting to literal IPs
allowPrivateIPs	false	Allow RFC1918 destinations
allowLoopbackIPs	false	Allow loopback destinations
enableV2	true	Enable Wisp v2 extensions
enableTwisp	false	Enable Twisp
passwordAuth(Required)	false	Password auth
parseRealIP	true	Honor trustedHeaders from trustedProxies
bandwidthLimitKbps	0	Per-IP bandwidth limit (0 = off)
floodProtection	enabled	See example.config.json
reputation	enabled	Persistent IP reputation scoring

Credits

• soap phia – Writing mrrowisp
• Amplify – Adding protections against flooding

License

BSD-3-Clause. See LICENSE.