Run evrd

Quick start #

evrd keeps your IRC connection alive while you're away, buffers what you miss, and lets clients (native or web) attach and detach whenever you like. The quickest way to run it is with the published container images: ghcr.io/4evrd/evrd (the daemon and evrctl) and ghcr.io/4evrd/evrd-web (the web app on nginx).

1. Make a secret key

   It encrypts the network passwords evrd saves (SASL and server passwords) and secrets set in Admin → Settings. Keep a copy somewhere safe; without it they can't be read back.

   shell

   echo "EVRD_SECRET_KEY=$(docker run --rm --entrypoint evrctl ghcr.io/4evrd/evrd genkey)" > .env

2. Write a config file

   A single node needs no external database: SQLite holds accounts and an embedded Pebble store holds history.

   evrd.conf

   listen     ircs://:6697
   api        :8098
   db         sqlite:/var/lib/evrd/evrd.db
   history    pebble:/var/lib/evrd/history
   public_url https://bnc.example.org
   irc_host   bnc.example.org
   cookie_secure no   # until TLS is in front — then remove this line

3. Start evrd and the web app

   The web image proxies /api and /auth to evrd-api:8098, so name the daemon's service that (or point the web container at it with EVRD_API=host:port).

   docker-compose.yml

   services:
     evrd-api:
       image: ghcr.io/4evrd/evrd:latest
       command: ["-config", "/etc/evrd/evrd.conf"]
       environment:
         EVRD_SECRET_KEY: ${EVRD_SECRET_KEY}   # from .env
       volumes:
         - ./evrd.conf:/etc/evrd/evrd.conf:ro
         - evrd-data:/var/lib/evrd
       ports:
         - "6697:6697"   # IRC — clients attach here
       restart: unless-stopped
     evrd-web:
       image: ghcr.io/4evrd/evrd-web:latest
       ports:
         - "8080:80"     # web app; put TLS in front of it
       restart: unless-stopped
   volumes:
     evrd-data:

4. Create the first admin

   shell

   docker compose exec evrd-api evrctl -config /etc/evrd/evrd.conf \
     user add -admin james 'a-long-password'

5. Sign in and add a network

   Open the web app (port 8080, or your public_url once a TLS proxy is in front), sign in, and add a network such as irc.libera.chat on +6697. evrd dials it, registers, autojoins your channels and starts buffering. Then attach a native client.

Install on OpenBSD #

evrd runs natively on OpenBSD (amd64 and arm64), without Docker. One script installs it as a confined system daemon, with SQLite and the embedded Pebble history store, so there's no database server to run. One command, as root (ftp is OpenBSD's built-in downloader, so no curl is needed):

ftp -o - https://raw.githubusercontent.com/4evrd/evrd/main/deploy/openbsd/install.sh | sh

The questions come up at your terminal even though the script arrives through a pipe. Not root? Use | doas sh. It downloads the latest release for your machine, checks it against the release's SHA256 file, and asks:

Then it starts evrd and prints the address. Open the ports in pf (/usr/local/share/examples/evrd/pf.conf has the rules). For Let's Encrypt, the names must already resolve to the machine, with ports 80 and 443 reachable. Every question has an option (-d host, -c certificate, -w evrd|relayd, -o SSO issuer, -a admin, …), passed as | sh -s -- -y -d bnc.example.org …. -y takes the defaults, for provisioning without a terminal. Run the same command again to upgrade: it keeps the config and the key. evrd restarts only if its program changed (a release that only touches the web app goes live without one), and even then nobody leaves IRC: the connection holder, evrd-links, keeps everyone's connections open while evrd restarts. Certificate renewals reload evrd (rcctl reload evrd) instead of restarting it.

How evrd is confined

rc.d starts evrd as root. It binds its ports and reads /etc/evrd/evrd.conf, the secret key and any certificate files, then:

1. chroots to /var/evrd, so the rest of the filesystem is gone;
2. becomes _evrd. The chroot and everything in it but data/ belong to root, so evrd can't change its own web app or name resolution;
3. unveils only its data, the web app and resolv.conf / hosts (read-only);
4. pledges stdio rpath wpath cpath fattr flock inet dns unix sendfd: it can't execute anything or open other kinds of sockets (unix sendfd hands connections to the holder).

evrd-links is confined the same way but tighter: chrooted to /var/evrd as _evrd, it pledges only stdio inet unix recvfd and can't open any files.

The same confinement works anywhere evrd starts as root, with chroot and user in evrd.conf (unveil and pledge are OpenBSD's). The full guide is in the repository: docs/openbsd.md.

Build from source #

evrd is pure Go (no cgo), so it cross-compiles anywhere Go 1.26 runs. The web client is a Svelte 5 + Vite app built with pnpm.

git clone https://github.com/4evrd/evrd.git && cd evrd
make build       # bin/evrd and bin/evrctl
make web         # web/build
./bin/evrd -version
./bin/evrd -config evrd.conf

Development stack

make up runs the whole stack with hot reload: an upstream ergo IRC server, two evrd nodes behind nginx, Postgres, ScyllaDB, VictoriaMetrics and the web client on http://localhost:5173. make e2e runs the Playwright suite against it.

Web client #

The web app shows your networks, channels and private messages with unread counts, mentions, members and topics, and stays in sync with every attached IRC client. Anything you send there shows up in your other clients too, because all sessions share one upstream connection.

The chat input understands /join, /part, /msg, /query, /me, /notice, /nick, /topic, /mode, /kick, /close, /quote and /help, and runs *status commands with /status help (all but jump, playback and detach, which are for IRC clients).

Native IRC clients #

Point HexChat, irssi, WeeChat or any other IRC client at the bouncer and authenticate with a server password:

The password is either your account password or an IRC client password made on the web app's IRC clients page. Client passwords are the only option for accounts that sign in with SSO, and you can revoke them one client at a time.

/connect -tls bnc.example.org 6697 james/libera:a-long-password

What you get on connect

• The welcome burst, your channels with names and topic, backlog replay, then live traffic.
• /join and /part update the network's saved channel list, and /nick changes your nick upstream.
• Your own notices and /me actions are saved and shown on your other clients.
• Capabilities echo-message and server-time.

Channel events in backlog

Joins, parts, quits, kicks, nick changes, topics and modes are saved alongside messages. On replay they come from *buffextras as plain text, for example bob is now known as robert, the same way ZNC's buffextras module does it, so they never confuse a client's nick list.

*status commands #

/msg *status help lists the bouncer's own commands. ZNC's names work too: listnetworks, jumpnetwork, addnet, delnet, listchans, shownetwork, setnetwork and the …TrustedServerFingerprint commands.

Servers, certificates and tuning

listservers, addserver, delserver, listfingerprints, addfingerprint, delfingerprint (and ZNC's AddTrustedServerFingerprint names), detach, and set for altnick, sasluser, bindhost, quitmsg, encoding, trustallcerts, trustpki, floodrate, floodburst, joindelay.

Network settings #

Each network has its own page in the web app (/networks/<id>) with everything ZNC offers without modules.

• Servers: several, each with host, port, TLS and an optional server password. evrd connects to the first and moves on to the next with each reconnect attempt.
• Identity: nick, alternate nick, ident, real name, quit message and bind host. Empty fields use the account defaults.
• Authentication: SASL PLAIN account and password, sent as PASS if the network has no SASL.
• Certificates: verify with system CAs (TrustPKI), trust everything (TrustAllCerts), or trusted SHA-256 fingerprints. When a certificate is refused, its fingerprint is shown with a button to trust it.
• Channels: key, detached (joined and logged but hidden from IRC clients until they /join), join-on-connect.
• Advanced: encoding for non-UTF-8 networks, flood protection (lines per second and burst), join delay.

Per-user settings

Under Account → Bouncer: default ident, quit message and bind host; how many lines to play back, and whether channels and private messages only replay what arrived since you were last attached; timestamps for clients without server-time; fixed CTCP replies; and the addresses allowed to sign in.

Configuration #

evrd reads one plain-text file of directive value lines (a space between them); pass it with evrd -config evrd.conf or set EVRD_CONFIG. A # starts a comment, at the start of a line or after a space. These are the directives you'll set first:

History backends

Chat history never goes in Postgres. ScyllaDB is shared by every node, with one partition per buffer per month and queued writes (up to 16k lines) so a slow database doesn't stall IRC. Pebble is an embedded store on local disk for single-node installs. evrctl history copy <from> <to> copies history between them.

HTTPS and certificates #

evrd's own TLS ports (the ircs:// IRC listeners, and the web app when evrd serves HTTPS itself) share one certificate source. Set it with tls, or switch it while evrd runs under Admin → Settings → HTTPS & TLS:

Certificates evrd gets or makes, and its ACME account, are kept in the database, encrypted with secret_key. Every node of a cluster serves the same ones, and nothing is written to disk.

Who serves HTTPS

evrd itself: set https_listen and http_listen, and web_root to the built web app. No proxy or web server is needed. Port 80 redirects to HTTPS and answers Let's Encrypt's http-01 challenge, and 443 answers tls-alpn-01.

public_url   https://bnc.example.org
irc_host     bnc.example.org
https_listen :443
http_listen  :80                     # redirects, and Let's Encrypt's challenges
web_root     /var/lib/evrd/web       # the release archive's web/
tls          acme
acme_email   ops@example.org         # optional: expiry notices

A proxy in front (nginx, Caddy, Traefik, relayd, a cloud load balancer): leave https_listen unset. The proxy terminates TLS and forwards to api, including the WebSocket, and evrd's certificate is then only for the IRC ports. This is how the Docker images run.

The settings page says which of the two is in use, and shows each certificate's issuer, names and expiry, or why getting one failed. Saving a choice that can't work (Let's Encrypt for localhost, say) is refused.

Accounts and sign-in #

Every user has a role (user or admin), per-user limits and optional suspension. Web sessions are stored in the database behind an HttpOnly cookie, so they survive restarts, and users can see and revoke them on their Account page.

SSO with OpenID Connect

Use Logto or any OIDC provider; SAML and social logins are connectors in the provider. Accounts are created on first sign-in and linked by the token's subject.

public_url         https://bnc.example.org   # callback: <public_url>/auth/callback
oidc_issuer        https://id.example.org/oidc
oidc_client_id     <app id>
# secret: oidc_client_secret, or EVRD_OIDC_CLIENT_SECRET
oidc_label         IRCforever account
oidc_auto_create   yes
oidc_link_existing no
oidc_admin_role    evrd-admin

Provisioning API

For tools that bring users in from elsewhere, such as moving ZNC users over, evrd can create an account and its networks before the owner ever signs in. It's off until provision_token is set (or EVRD_PROVISION_TOKEN), and every call sends that token:

curl -X PUT http://127.0.0.1:8098/api/provision/users/alice \
  -H "Authorization: Bearer $EVRD_PROVISION_TOKEN" \
  -d '{"email": "alice@example.org", "connect": true,
       "networks": [{"name": "libera", "host": "irc.libera.chat", "port": 6697,
                     "tls": true, "nick": "alice", "channels": ["#evrd"]}]}'

Networks take the same fields as the web app's network editor. Each one comes back as created, exists (so a call can be repeated) or failed. connect connects every listed network, so a migration can create everything, take the old bouncer off IRC, then call again to connect. A new account has no password and is claimable: the first SSO sign-in with the same username and email links to it. Keep the token secret and the API on a local address.

Suspending a user signs them out everywhere, drops their IRC clients and disconnects their networks; lifting the suspension reconnects them. The last active admin can't be demoted, suspended or deleted.

Server settings #

Admins can change the general, limits, connection (connect_rate, bindhost), HTTPS & TLS, sign-in, single sign-on and metrics settings from Admin → Settings. Each value comes from, in order (later wins):

1. built-in defaults
2. evrd.conf
3. the database: values set on the Settings page, shared by every node
4. the environment on that node (EVRD_OIDC_CLIENT_SECRET, EVRD_METRICS_URL, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT)

Most settings apply live on every node within a few seconds. public_url, the SSO provider, metrics export and the certificate file paths are marked Restart needed. With the connection holder running, that restart doesn't take anyone off IRC. Startup and per-node settings (listen, api, https_listen, http_listen, web_root, chroot, user, db, history, cluster settings, upstream_bind / upstream_prefix6, secret keys, settings_write_conf) stay in the file or environment.

Saved passwords #

Network passwords (the SASL password and server passwords) and the values set in Admin → Settings (such as the SSO client secret) are encrypted in the database with AES-256-GCM under a key that lives outside it. Account and client passwords are bcrypt hashes either way.

# make one with: evrctl genkey
secret_key      <32 bytes, base64>   # or EVRD_SECRET_KEY, or secret_key_file /path
secret_key_old  <previous key>       # optional: still decrypts while rotating

Rotating the key

Set the new secret_key, move the old one to secret_key_old, restart, then remove the old key. At startup evrd encrypts anything saved before a key was set and re-encrypts anything under an old key, network passwords and settings alike. Every node needs the same key; keep it out of database backups.

Running several nodes #

Run any number of nodes against the same Postgres and ScyllaDB, behind a plain round-robin load balancer for IRC (TCP passthrough) and the API (HTTP + WebSocket). Each user is owned by one node, which runs their network connections and serves their clients; any other node forwards that user's traffic to it.

If a node dies, its users move to the others in about 20 seconds (cluster_lease); on shutdown a node hands them over within one tick (5 s).

internal_listen      :8099   # internal HTTP — between nodes only
internal_irc_listen  :6699   # internal IRC — between nodes only
history              scylla://db1,db2/evrd

EVRD_NODE_ID=node-a
EVRD_INTERNAL_URL=http://evrd-a.internal:8099
EVRD_INTERNAL_IRC_ADDR=evrd-a.internal:6699
EVRD_CLUSTER_SECRET=<the same long random secret on every node>

The repository ships a tested nginx config (deploy/lb.conf) and a Traefik equivalent (deploy/traefik/, Traefik ≥ 3.7 for TCP health checks). With internal_listen set, all four of cluster_secret, internal_url, internal_irc_listen and internal_irc_addr are required (as directives, or the environment variables above). A lone node without internal_listen still works and owns every user.

Connections to networks #

Large networks throttle and cap connections per source address, and every user on a node would otherwise share the node's address.

connect_rate     5                       # most connects/second to one server, per node
upstream_bind    192.0.2.10 192.0.2.11   # spread users over these (stable per user)
upstream_prefix6 2001:db8:42::/64        # each user's own IPv6 address (IPv6 servers)
bindhost         192.0.2.20 vhost.example.org

A prefix needs Linux and a local route: ip -6 route add local 2001:db8:42::/64 dev lo. bindhost lists addresses users may pick to connect from, like ZNC's BindHost. Admins can use any address and can lock a user's choice.

Metrics #

evrd exports OpenTelemetry metrics over OTLP/HTTP and reads them back from VictoriaMetrics for the dashboard's traffic chart and health numbers.

otel_endpoint http://victoriametrics:8428/opentelemetry/v1/metrics
otel_interval 15s
metrics_url   http://victoriametrics:8428

Run VictoriaMetrics with -opentelemetry.usePrometheusNaming to get evrd_irc_lines_total, evrd_upstream_up, evrd_upstream_lag_seconds, evrd_irc_clients, evrd_cluster_users, evrd_history_queue and friends. Without metrics_url the dashboard still works, and the chart says metrics are off.

Behind a proxy with basic auth, put the credentials in both URLs (https://user:pass@vm.example.org). evrd sends them as basic auth, and Admin → Settings shows the password masked.

evrctl #

Command-line admin for a running install: evrctl [-config file | -db dsn] <command>. -config defaults to $EVRD_CONFIG; it writes to the database directly.

Releases and versions #

Releases are cut automatically by semantic-release from Conventional Commits on main. Each release is tagged vX.Y.Z, gets GitHub release notes grouped by type, and tags the images :X.Y.Z and :X.Y. Every push to main also publishes :latest and :sha-<commit>. evrd -version reports the version.

evrd stays at 0.x until a breaking change says otherwise. Get the latest release →