Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MercuryWorkshop/epoxy-tls/llms.txt

Use this file to discover all available pages before exploring further.

epoxy-server is a performant, multi-threaded server implementation of the Wisp protocol, written in Rust and built specifically for use with epoxy-client. It multiplexes TCP and UDP streams over a single WebSocket (or length-delimited) connection, giving browser-based clients full network access through an unprivileged channel. The server uses jemalloc as its allocator and the Tokio async runtime, and is designed to handle many concurrent Wisp clients with minimal overhead.

​
Key features

Multi-threaded Tokio runtime

Choose between SingleThread, MultiThread (default), or ThreadPerCore runtimes to match your deployment hardware.

Wisp v1 and v2

Full support for both Wisp protocol versions, including v2 extensions for UDP, MOTD, password auth, and certificate auth.

Flexible listener types

Accepts connections on plain TCP, TLS-wrapped TCP, Unix domain sockets, or TLS-wrapped Unix domain sockets.

WebSocket and length-delimited transports

Serves Wisp over standard WebSocket upgrades or a raw little-endian length-delimited codec (LengthDelimitedLe).

Password and certificate authentication

When Wisp v2 is enabled, clients can be required to authenticate with a username/password pair or an ed25519 certificate before any streams are accepted.

Host and port filtering

Regex-based allow and block lists for hostnames (with separate TCP and UDP overrides) and inclusive port range allow/block lists guard which destinations clients can reach.

Stats endpoint

An optional HTTP stats endpoint exposes live connection and stream information. Stats can also be printed to the log by sending SIGUSR1 to the process.

TLS listener support

Supply a PEM keypair in the config to terminate TLS directly on the Wisp listener, without an external reverse proxy.

​
Architecture overview

Browser / epoxy-client
        │  WebSocket (or LengthDelimitedLe)
        ▼
  epoxy-server  ──►  TCP/UDP destination
  (Wisp mux)         (e.g. api.example.com:443)
epoxy-client opens a single persistent WebSocket connection to epoxy-server. Inside that connection it multiplexes independent Wisp streams — each stream represents one outbound TCP or UDP flow to a destination host and port. epoxy-server de-multiplexes the streams, opens real OS-level sockets to the destinations, and bidirectionally pipes data. From the perspective of the destination server the connections originate from the host running epoxy-server, not from the browser.

​
Next steps

Building

Compile epoxy-server from source with optional performance flags.

Running

Generate a config file and start the server.

Configuration

Full reference for every config key in the TOML/JSON/YAML config file.

Build docs developers (and LLMs) love

Get started for freeTalk to us