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.

Once you have a compiled epoxy-server binary (see Building), getting the server running takes only a few steps: generate a default configuration file, edit it to suit your environment, and launch the binary. epoxy-server reads its runtime configuration from a single TOML, JSON, or YAML file. The log level can also be overridden at runtime with the standard RUST_LOG environment variable (e.g. RUST_LOG=debug epoxy-server config.toml).

​
Quick start

1

Generate the default configuration

Print the built-in defaults to a file so you have a starting point:
epoxy-server --default-config > config.toml
The file is written in TOML by default. To generate JSON instead, pass --format before --default-config:
epoxy-server --format json --default-config > config.json
YAML output is also supported if epoxy-server was compiled with the yaml feature:
epoxy-server --format yaml --default-config > config.yaml
2

Edit the configuration file

Open config.toml in your editor and adjust it for your deployment. The most common settings to change are:
  • server.bind — the address and socket type to listen on (default: ["tcp", "127.0.0.1:4000"])
  • server.tls_keypair — paths to your PEM certificate and key if you want epoxy-server to terminate TLS directly
  • wisp.wisp_v2 — enable or disable Wisp version 2 extensions
  • wisp.auth_extension — set to "password" or "certificate" to require client authentication
  • stream.allow_hosts / stream.block_hosts — regex lists controlling which destinations clients may reach
See the configuration reference for every available key.
3

Start the server

Pass the path to your configuration file as the sole positional argument:
epoxy-server config.toml
epoxy-server logs to standard output. The first line printed will confirm the address, runtime flavour, and transport:
[INFO  epoxy_server] listening on (Tcp, "127.0.0.1:4000") with runtime flavor MultiThread and socket transport WebSocket

​
CLI reference

ArgumentShortDescription
<config>—Path to the configuration file (TOML by default). If omitted, built-in defaults are used.
--format <fmt>-fConfig file format: json (always available), toml (requires the toml feature, enabled by default), or yaml (requires the yaml feature). When the toml feature is compiled in, toml is the default format. Must precede the config path if used together.
--default-config—Print the default configuration in the selected format and exit immediately.
Use --format json --default-config to get the defaults as JSON — convenient for piping into tools like jq or for bootstrapping an automated deployment that stores config as JSON:
epoxy-server --format json --default-config | jq '.server.bind'

​
Running as a systemd service

For long-running deployments, manage epoxy-server with systemd. Create a unit file at /etc/systemd/system/epoxy-server.service: 
[Unit]
Description=epoxy-server Wisp proxy
After=network.target

[Service]
Type=simple
User=epoxy
Group=epoxy
ExecStart=/usr/local/bin/epoxy-server /etc/epoxy-server/config.toml
Restart=on-failure
RestartSec=5s

# Allow binding to privileged ports if needed (e.g. 443)
# AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
Enable and start the service: 
sudo systemctl daemon-reload
sudo systemctl enable --now epoxy-server
sudo systemctl status epoxy-server
To print a stats snapshot to the journal at any time, send SIGUSR1: 
sudo systemctl kill -s USR1 epoxy-server
By default epoxy-server binds to 127.0.0.1:4000 and serves plain WebSocket connections without TLS. If you expose it to the internet you should either place a TLS-terminating reverse proxy (such as Nginx or Caddy) in front of it, or configure a TLS listener directly in the config by setting server.bind to ["tlstcp", "0.0.0.0:443"] and providing server.tls_keypair with paths to your PEM certificate and private key.

Build docs developers (and LLMs) love

Get started for freeTalk to us