Self-Hosting the Relay Hub
The relay hub is an optional, self-hosted server that turns xacpx into a multi-tenant remote-control dashboard. Your xacpx instances dial out to the hub over WebSocket and register; you then log in to a web dashboard from any browser and drive every instance's sessions — chat, scheduled tasks, and orchestration — from one place.
This guide walks an operator from nothing to a running hub with a paired instance.
Architecture at a glance
xacpx instance A ─┐ ┌─ browser (token login)
xacpx instance B ─┤ WSS (dial-out) │ HTTPS + WSS
xacpx instance C ─┴──────────────► RELAY HUB ◄───────────┘
:8787 HTTP API + web /ws + instance gateway
│
relay.db (SQLite)- Single port (by default). The HTTP API, the dashboard's
/wsfan-out, and the instance WebSocket gateway (where xacpx instances register) all share 8787 — connectors register via a WebSocket upgrade at the root path. Pass--ws-portonly if you want a dedicated gateway port you can firewall independently. - Multi-tenant. Every token-user only ever sees its own instances and sessions; the server stamps identity on each proxied call. Tokens, instance credentials, and web-session cookies are stored hashed.
- Source of truth stays on the instances. The hub caches recent messages for the dashboard but does not own your sessions — the instances do.
Requirements
- Node.js ≥ 22.13 (uses the built-in
node:sqlite) or Bun ≥ 1.2 (usesbun:sqlite). No native database addon to compile. - A host reachable by your instances and your browser. For anything beyond localhost you want a TLS-terminating reverse proxy (see TLS & reverse proxy).
- To pair instances, each instance needs the
xacpxCLI (the normal install from Getting Started).
1. Get the server
Install the relay hub globally. The web dashboard ships embedded inside the package, so this one install is everything you need — no separate dashboard build, no --web-root:
npm i -g @ganglion/xacpx-relayThis puts the xacpx-relay binary on your PATH. The bundled dashboard is auto-detected at startup; the start command prints its resolved path (shown below).
Run from source instead (development / contributing)
Clone the repo and build the server — build:relay also builds the dashboard and embeds it into packages/relay/dist/relay-web:
git clone https://github.com/gadzan/xacpx
cd xacpx
bun install && bun run build:relayThe entry point is then packages/relay/dist/cli.js — run node packages/relay/dist/cli.js <command> in place of xacpx-relay <command> everywhere below.
2. Quickstart (zero flags needed)
Auth is entirely token-based — no passwords, no admin accounts. A token IS a user. Mint one and start the server:
# Step A — create a user + token (DB auto-created at ~/.xacpx-relay/relay.db)
xacpx-relay add token
# Step B — start the server (uses the same default DB; dashboard auto-detected)
xacpx-relay startadd token prints the token once:
access token: bBS9nN2W2MwdrdksoLTLrQeMLMah9M5flTOyEcBbIHc
(store it now — not shown again)
hint: use this token for web login AND: xacpx channel add relay --url <host> --token <token>start confirms what is running:
xacpx-relay listening: http :8787, instance gateway: merged on http :8787 (path / or /gateway), db ~/.xacpx-relay/relay.db, dashboard: /usr/lib/node_modules/@ganglion/xacpx-relay/dist/relay-webOpen http://<host>:8787, paste the token into the Access token field, and you are in.
3. Token management
All hub administration happens through a handful of CLI subcommands (add token / add invite / ls / rm token / rm invite / start / update); all flags are optional:
add token — create a user + login token
xacpx-relay add token [--label <note>] [--db <path>]Each call creates an isolated user and prints its access token once. The same token is used to:
- Log in to the web dashboard (paste into Access token).
- Pair an xacpx instance (
--token <T>inchannel add relay).
Reuse the same token across multiple instances to group them under one user.
ls — list tokens
xacpx-relay ls [--db <path>]Shows: short id, label, created date, number of paired instances.
rm token — revoke a token (and its user)
xacpx-relay rm token <value-or-id> [--db <path>]Deletes the user behind that token and cascades to its instances, web sessions, and cached messages. Revocation kills that token's web sessions on the next request; an already-open dashboard /ws socket lingers until reconnect. To hard-cut all sessions: stop the hub, run sqlite3 <db> "DELETE FROM web_sessions;", then restart.
add invite — invite someone via a link
When you can't (or don't want to) mint a token on the server for someone else, hand them a single-use invite link instead:
xacpx-relay add invite [--label <note>] [--ttl <n>{m|h|d}] [--url <base>] [--db <path>]Prints the invite code once, plus a ready-to-share redeem link when --url is given (otherwise a /invite/<code> path to append to your hub URL):
invite code: mJ3…
redeem link: https://relay.example.com/invite/mJ3…
(share it now — single-use, not shown again; expires 2026-08-02 12:00 UTC)Opening the link shows a redeem page; the recipient clicks to redeem (link previews and crawlers can't burn the code), which creates a fresh account and shows its access token exactly once — same semantics as add token, just self-service.
--ttldefaults to7d(e.g.30m,12h,3d; capped at 10 years).- Codes are single-use and hashed at rest; used/expired codes are swept hourly.
- The redeem endpoint shares the login rate-limit bucket (per-IP — remember
--trust-proxybehind a proxy). lsgains an invites section (short id, label, expiry, statusunused|used|expired); remove one withrm invite <code-or-id>(does not affect already-redeemed accounts).
Invite links appear in proxy logs
The plaintext code travels in the URL path, so your reverse proxy's access log will record unredeemed invite links (once redeemed they're worthless). If that matters to you, use a short --ttl or disable access logging for /invite/ paths.
start — start the server
xacpx-relay start \
[--db <path>] \
[--web-root <dir>] \
[--host 0.0.0.0] \
[--http-port 8787] \
[--ws-port <n>] \
[--history-retention-days 30] \
[--request-timeout-ms 120000] \
[--trust-proxy]| Flag | Default | Purpose |
|---|---|---|
--db <path> | ~/.xacpx-relay/relay.db | SQLite database file. The directory is created automatically. |
--http-port <n> | 8787 | HTTP API and the dashboard's /ws fan-out. |
--ws-port <n> | (merged) | Omit to merge the instance gateway onto the HTTP port (single-port default). Pass a port to run a dedicated gateway listener you can firewall separately. |
--host <addr> | 0.0.0.0 | Bind address. |
--web-root <dir> | (auto-detected) | Dashboard assets directory. Auto-resolves the dashboard embedded in the package (dist/relay-web next to cli.js); only pass this to override. |
--history-retention-days <n> | 30 | Cached messages older than this are pruned hourly (also hard-capped at 2000 messages per session). |
--request-timeout-ms <n> | 120000 | Per-request timeout for proxied calls to instances. |
--trust-proxy | (off) | Trust X-Forwarded-For for rate limiting. Pass this when behind a reverse proxy; never when directly internet-exposed (it would allow IP spoofing). |
There is no stop/status subcommand — stop the hub with Ctrl-C / SIGTERM (run it under systemd, pm2, or Docker for lifecycle management).
Rate limiting
The hub enforces a per-client-IP rate limit plus a global failure ceiling. When running behind a reverse proxy, pass --trust-proxy so the real client IP from X-Forwarded-For is used for rate limiting, not your proxy's loopback address.
4. Pair an xacpx instance
Attach the instance
On the machine running the xacpx instance, add the relay connector channel using the same token you created in step 2:
xacpx plugin add @ganglion/xacpx-channel-relay
xacpx channel add relay --url relay.example.com --token <T> [--name home-pc]
xacpx restartPoint --url at the same host as the dashboard — a bare domain resolves to wss://relay.example.com, and the merged gateway shares that host. xacpx plugin add installs the connector from npm and pulls in its @ganglion/xacpx-relay-protocol dependency automatically. The instance's xacpx core must be ≥ 0.24.10-beta.18 (the connector's peer requirement).
Pairing from a source checkout (development)
If you run the instance from a repo checkout, the workspace already links channel-relay and relay-protocol — skip plugin add and run xacpx channel add relay … directly.
--url shorthand rules
--url accepts any of the following; the connector normalizes it to a full WebSocket URL:
| What you pass | Resolved to |
|---|---|
relay.example.com (bare domain) | wss://relay.example.com |
1.2.3.4 (IP) | ws://1.2.3.4:8787 |
1.2.3.4:9000 | ws://1.2.3.4:9000 |
localhost | ws://localhost:8787 |
host:9000 | ws://host:9000 |
ws://… or wss://… | used as-is |
http://… or https://… | mapped to ws://… / wss://… |
IPv6
Bare unbracketed IPv6 addresses are not supported. Use [::1]:8787 instead.
How pairing works
On first connect the instance exchanges the access token for a long-lived per-instance credential, written (mode 0600) to <xacpx-home>/relay/credential.json. The pairing token itself is persisted in ~/.xacpx/config.json alongside the url/name — treat that file as secret, because the token is exactly what an attacker needs to impersonate the instance. The token is used only at first pairing — all subsequent reconnects use the stored credential.
One token, multiple instances
Reuse the same token on several instances (e.g. home-pc, work-laptop). They all appear under the same user in the dashboard.
Upgrading from the two-port (0.1.0) layout
The default moved to a single port. A connector that was paired against the old 8788 gateway has a ws://<host>:8788 URL frozen in its config.json (the URL is normalized once, at channel add time), so it will keep dialing :8788. Re-run xacpx channel add relay --url <host> … (or edit the stored url) so it points at the merged HTTP port. Bare-domain connectors (wss://host, no port) are unaffected — they already land on the merged gateway.
Back in the dashboard, the instance appears in the left column with a green dot once it is online. Select a session to chat; open the task panel (right column, or the Tasks button on mobile) for scheduled and orchestration tasks.
TLS & reverse proxy
The hub speaks plain HTTP and WS. For any non-localhost deployment, terminate TLS at a reverse proxy and forward the single HTTP port. Instances should then connect with wss://.
The dashboard's live updates use a WebSocket upgrade on the HTTP port, so the proxy must allow upgrades on that route. The merged instance gateway rides the same port via a WebSocket upgrade at the root path, so the single proxied route covers both.
Caddy
relay.example.com {
reverse_proxy 127.0.0.1:8787
}Caddy auto-proxies the WebSocket upgrades for both the dashboard /ws and the gateway root — no extra config.
nginx
server {
listen 443 ssl;
server_name relay.example.com;
# ssl_certificate ...; ssl_certificate_key ...;
location / {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}Keep desktop tickets out of access logs
If you enable instance Desktop (RFB/VNC), the browser and the connector each open a WebSocket whose ticket must ride the query string:
/desktop/observe?ticket=<browser-ticket>
/desktop/instance?ticket=<connector-ticket>The browser WebSocket API cannot set a custom authentication header, so the query string is the only transport there; the connector side follows the same shape so both planes behave identically. xacpx's own logs never write these tickets (the connector reports origin+path only), but any proxy that logs the request URI records them in cleartext.
Tickets are single-use with a 60s TTL and are consumed during the upgrade, so a leaked ticket is usually already dead — but treat it like the /invite/<code> case: disable access logging for these paths.
Caddy — declare the matcher and the skip as site-scope directives:
relay.example.com {
@desktop_ticket {
path /desktop/observe* /desktop/instance*
}
log
log_skip @desktop_ticket
reverse_proxy 127.0.0.1:8787
}log_skip is an HTTP directive in its own right — it is not a reverse_proxy subdirective, so it must sit in the site (or route) block. log is what actually emits the access log; if you never configure log, Caddy writes no access log and there is nothing to skip. With a named logger (log <name> { ... }), keep log_skip as a sibling directive and pass the matcher to it the same way — it applies to that logger's entries.
log_skiprequires Caddy 2.8+. On older Caddy the directive was namedskip_log; use that name instead ifcaddy validaterejectslog_skip.
nginx — keep the proxying but stop logging these two locations:
# Ticket-bearing WebSocket upgrades: must NOT appear in access logs.
location ~ ^/desktop/(observe|instance) {
access_log off;
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}The regex location must be declared so it wins over location / for these paths (nginx prefers the longest literal prefix but regexes are checked in order — place it as shown, or use location ^~ /desktop/ if you prefer a prefix match).
Server-side setup for a supported RFB server is in docs/desktop-rfb-setup.md; the terser operator runbook is docs/relay-deployment.md.
Advanced: dedicated gateway port (--ws-port)
If you start the hub with xacpx-relay start --ws-port 8788, the instance gateway gets its own port instead of riding the HTTP port. You can then add a second proxied domain (gateway.example.com → 8788) and point connectors at wss://gateway.example.com. This is only needed if you want to firewall the gateway apart from the dashboard.
Which ports to expose
| Port | Audience | Expose publicly? |
|---|---|---|
| 8787 | Browsers (dashboard + API + dashboard /ws) and xacpx instances (merged gateway) | Yes, behind TLS |
| 8788 | Only if you opt into --ws-port — dedicated instance gateway | Yes, behind TLS |
| — | relay.db | Never — it is a local file |
Instance Desktop (RFB/VNC)
Each online instance can optionally expose its local graphical desktop to the dashboard, so you can watch and control the machine itself — not just its sessions. This section is the English companion to the per-platform setup and diagnosis guide; the full reference is docs/desktop-rfb-setup.md (Chinese) and the operators' runbook is docs/relay-deployment.md.
What you get, and what you don't
| Current | |
|---|---|
| Supported servers | RFB servers that offer outer VNC Auth (security type 2), and macOS Screen Sharing (Apple Remote Desktop, type 30, terminated on the connector) |
| Platforms | Linux, Windows, and macOS interactive user sessions |
| Viewers | One desktop stream per instance at a time |
| Transport | A separate binary WebSocket — framebuffer never enters the control plane, so desktop traffic can not block chat or terminal input |
| Ports | None added publicly. The connector dials 127.0.0.1:<port> on the instance; 5900 is never exposed to the internet |
| Auth schemes rejected by design | None (no auth), Tight-only, VeNCrypt/TLS-only, and proprietary auth |
| Not in this release | Multi-viewer, file transfer, clipboard sync, session recording |
Enabling desktop advertises desktop.rfb.v1 and desktop.ard-auth.v1. An instance without desktop.rfb.v1 simply shows no Desktop entry in the dashboard. macOS sign-in asks for an account name and password in the tab; nothing is stored, and a reconnect asks again.
Enable it on the instance
Desktop is opt-in per instance, in the channel-relay config the connector already uses:
{
"channels": {
"relay": {
"enabled": true,
"options": {
"url": "wss://relay.example.com",
"desktop": {
"enabled": true,
"port": 5900,
"connectTimeoutMs": 1500,
"maxStreams": 1
}
}
}
}
}| Option | Default | Notes |
|---|---|---|
enabled | false | Master switch. Omit or false → no stream state is created at all. |
port | 5900 | Integer 1–65535. This is the port the connector dials on loopback — the setup guidance and error messages report exactly this value. |
connectTimeoutMs | 1500 | 250–10000. Shared by the loopback TCP dial, the banner preflight, and the hub upgrade. |
maxStreams | 1 | Fixed at 1 for v1 (single-viewer) — any other value is rejected when the config is parsed. |
host / hostname / target are rejected — the target is fixed to loopback, so the connector can never become a general TCP proxy.
The VNC password is entered in the dashboard per tab and kept in tab memory only: it is never written to disk, never logged, and never carried in the URL.
Windows (TightVNC)
- Install TightVNC and run the server in the logged-in user session — not as a service. A service session shows a different (empty) desktop.
- Authentication: set VNC password mode. The primary password must be set; keep "Require user authentication" off unless you also intend to type a Windows username into the dashboard.
- Confirm the outer security list offers type 2 (VNC Auth). Servers that only offer Tight (outer type 16) are rejected — a Tight-only endpoint can negotiate sub-auth down to no-auth.
- Access control: use LoopbackOnly access control plus the Windows Firewall.
LoopbackOnlyis access control, not a bind-address control — binding to0.0.0.0with loopback-only access control is an accepted deployment, because external connections are still refused. - Verify locally, then verify externally:
netstat -ano | findstr :5900Prefer 127.0.0.1:5900. If you see 0.0.0.0:5900, that is not by itself a failure — the accepted deployment is 0.0.0.0 bind + loopback-only access control + firewall. Confirm instead that 5900 is unreachable from a second machine.
Locked screen, UAC, and the login screen are not guaranteed. This is a hard limitation of the Windows interactive desktop, not a bug:
- After you lock the workstation, TightVNC keeps rendering but keystrokes and mouse events do not reach the lock screen. The dashboard shows a live-looking picture with no input effect.
- UAC elevation renders on the secure desktop, which VNC can neither see nor drive.
- To remote a host, it must be already logged in. Use platform RDP/remote management if you need the login screen.
Linux (TigerVNC / x11vnc)
Standard VncAuth, and the RFB server must refuse external connections:
ss -ltnp | grep 5900Prefer 127.0.0.1:5900. An 0.0.0.0 bind is not automatically wrong, but it must come with access control/firewall and must be verified unreachable from another machine.
- TigerVNC / x11vnc — standard VncAuth, preferred.
- WayVNC — the default secure configuration is rejected. It must run in legacy VncAuth compatibility mode (
relax_encryption+allow_broken_crypto). This is a deliberately weak transitional setup: acceptable while it stays loopback-only, unsuitable to copy into any non-loopback deployment. It also requires WayVNC 0.10.0 or newer (legacy DES auth landed there). - GNOME Screen Sharing (VeNCrypt v1) — unsupported in Phase A.
macOS
macOS Screen Sharing is a supported path: the connector performs the Apple Remote Desktop (type 30) handshake on the instance (desktop.ard-auth.v1) and the browser sees an ordinary RFB 3.8 stream.
- System Settings › General › Sharing › Screen Sharing, and allow the account you intend to sign in with.
- Grant Screen Recording and Accessibility when macOS prompts.
- Unless you deliberately want the VNC-password path, turn off "VNC viewers may control screen with password" — a Mac that offers both takes the VNC password path.
In the dashboard, click Desktop: the tab asks for the macOS account name (short or full name) and password. They travel over your already-authenticated control connection to that Mac's connector, are used only for the ARD handshake, and are then dropped — nothing is stored, and every reconnect asks again (the account name is prefilled). A connector build too old to do ARD pre-auth reports desktop-auth-unsupported; update @ganglion/xacpx-channel-relay.
Diagnosing a failed open
Errors surface in the dashboard banner with a stable code plus the RFB server's own rejection text, and the guidance is platform-specific — follow it verbatim.
| Code | Meaning | Fix |
|---|---|---|
desktop-disabled | Desktop not enabled on the instance | Set enabled=true, reconnect the connector |
desktop-busy | A viewer is already attached | Close the other Desktop tab |
desktop-rfb-unavailable | Loopback port refused | VNC server not started, or configured port is wrong — the message names your configured port |
desktop-not-rfb | Port answers, but it is not RFB | desktop.port points at a different service |
desktop-auth-unsupported | Auth scheme not accepted | Tight-only outer 16 / VeNCrypt / None / proprietary — see the platform sections above |
desktop-credentials-required | macOS wants an account name and password | The tab shows a form, not an error banner |
desktop-credentials-rejected | macOS rejected the account name or password | The form stays open; correct them, or allow the account in Screen Sharing |
desktop-permission-denied | Signed in, but macOS did not start the session | Check Screen Sharing, Screen Recording, and Accessibility |
desktop-protocol-error | The RFB handshake broke the protocol contract | Check the RFB server type and version; see the platform sections above |
desktop-stream-timeout | Tunnel or upgrade timed out | Transient; retry |
desktop-instance-offline | Instance went away | Wait for it to come back; retry |
Where to look:
- Hub log —
relay.desktop.stream.*:stream_active,stream_closed(with reason), plustext_frame,oversize_frame,backpressure_close,preattach_overflow. - Connector log —
relay.desktop.probe_rejected(includes the RFB server's owndetail),probe_ok,tunnel_failed. - Dashboard — the banner shows the code plus detail; a wrong VNC password reports auth failure in the password field instead of a generic timeout.
There is deliberately no separate desktop doctor command in Phase A. The open error is made diagnosable instead — the error code, the server's own rejection text, the platform-specific guidance, and the connector log — so no new doctor framework is introduced for this feature.
Token & user management
- More users/instances: run
add tokenagain — each call creates an isolated user. Reuse the same token on multiple instances to group them under one user. - Audit:
lsshows all tokens with their labels, creation dates, and instance counts. - Revoke:
rm token <value-or-id>removes the user and cascades to its instances, web sessions, and cached messages. The token's web sessions are killed on the next request; open/wssockets linger until reconnect. - Force global re-login: stop the hub,
sqlite3 <db> "DELETE FROM web_sessions;", restart. - Automatic GC: an hourly maintenance loop prunes cached messages past
--history-retention-days(and the 2000-per-session cap) and deletes expired web sessions. No cron needed.
Persistence & backup
Everything lives in the one SQLite file at --db (default ~/.xacpx-relay/relay.db). To back up, stop the hub (or snapshot during a quiet moment) and copy the file:
cp ~/.xacpx-relay/relay.db /backups/relay-$(date +%F).dbLosing it means losing all token-users, instance registrations, and cached history — instances would need to be re-paired.
Running under systemd (example)
# /etc/systemd/system/xacpx-relay.service
[Unit]
Description=xacpx relay hub
After=network.target
[Service]
# Use the absolute path to the installed binary — find it with `command -v xacpx-relay`.
ExecStart=/usr/bin/xacpx-relay start --host 127.0.0.1
Restart=on-failure
User=xacpx
[Install]
WantedBy=multi-user.targetBind to 127.0.0.1 and let your reverse proxy face the internet. The DB and dashboard are auto-detected from their defaults; add --db only if you want a non-default path.
Running under pm2 (example)
If you already run Node services under pm2, it supervises the hub just as well — xacpx-relay has no stop/status of its own, so a process manager handles restarts and boot-time startup.
pm2 start xacpx-relay --name xacpx-relay -- start
pm2 save # persist the process list
pm2 startup # prints a one-time command to enable boot-time startuppm2 resolves xacpx-relay from your PATH and stores its absolute path, so the saved process survives reboots. If pm2 can't find it (non-standard install), pass the full path from command -v xacpx-relay instead.
Or pin the arguments in an ecosystem file (pm2 start ecosystem.config.js):
module.exports = {
apps: [{
name: "xacpx-relay",
script: "xacpx-relay",
args: "start",
autorestart: true,
}],
};The defaults work out of the box. For a hardened setup, append flags to start: --host 127.0.0.1 to keep the hub off the public interface (behind your reverse proxy), --db <path> for a non-default database, or --trust-proxy so rate limiting uses the real client IP from X-Forwarded-For (see TLS & reverse proxy). After xacpx-relay update, run pm2 restart xacpx-relay to load the new version.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Dashboard 404 / blank page | start printed dashboard: (none) — the embedded UI wasn't found | The dashboard ships inside @ganglion/xacpx-relay; reinstall the package. From a source checkout, rebuild with bun run build:relay (it embeds the dashboard into dist/relay-web). |
| Instance never turns green | Wrong gateway URL or revoked/mistyped token | Point --url at the same host as the dashboard (the merged gateway shares the HTTP port); only use a separate :8788 host if you started the hub with --ws-port. Re-run add token and re-pair if the token was revoked. |
Custom --db not taking effect | --db passed inconsistently between commands | Pass the same --db path to both add token and start; the default ~/.xacpx-relay/relay.db is a fixed absolute path so omitting --db consistently is safe. |
| Live updates stall behind a proxy | Proxy not forwarding WebSocket upgrades on 8787 | Allow Upgrade/Connection headers on the dashboard route. |
See also
docs/relay-module.md— server + connector internals.docs/relay-web-module.md— dashboard architecture.- Design spec:
docs/superpowers/specs/2026-06-13-relay-hub-design.md.