Self-hosting the relay

What the relay does

The relay is a single server process. MangoSSH devices, host agents and browsers connect out to it over WebSockets, so nothing you manage needs an open inbound port. Which features use it:

SSH Persistent Sessions is turned on per host: open the host with Edit, go to Access, and tick Keep this session alive on MangoSSH's relay — reattach from any device.

What you need

• A Linux x86-64 machine that runs Docker, reachable from every device and agent that will use it. A small VPS is enough to start.
• Sized for the traffic you send through it. Pairing and forwarding for Connect by ID is light on CPU and limited by bandwidth: every relayed session passes through twice, in and out. Brokered RDP is the heavy case, because the relay runs the RDP client itself and decodes the screen. Add CPU as brokered RDP use grows. Check your provider's outbound traffic pricing before choosing.
• A domain name pointing at the machine, for a Let's Encrypt certificate.
• Ports 80 and 443 open. The relay's own port, 8878, stays private behind the proxy.

Step 1 — Install the relay

Download the relay bundle onto the machine and run its installer. The bundle holds a pre-built image, so nothing is compiled on your server.

1. Install Docker and the Compose plugin, if the machine doesn't have them.

   curl -fsSL https://get.docker.com | sh

2. Point DNS at the machine. Create an A record such as relay.yourteam.example and wait until it resolves. The certificate can only be issued once it does.

3. Download the bundle.

   curl -fLO https://downloads.mangossh.com/mangossh/latest/mangossh-relay-linux-x64.tar.gz

4. Check the download (optional). Print its SHA-256 and compare it with the relay line in SHA256SUMS-selfhost, linked under Self-host the servers in the downloads section. That list names the versioned file, such as mangossh-relay-1.0.99-linux-x64.tar.gz; it is the same file, so only the hash has to match. sha256sum -c would look for the versioned name and report it missing.

   sha256sum mangossh-relay-linux-x64.tar.gz

5. Unpack and install.

   tar -xzf mangossh-relay-linux-x64.tar.gz
   cd mangossh-relay-*-linux-x64
   sudo ./install.sh --domain relay.yourteam.example

6. Check it from outside: curl https://relay.yourteam.example/healthz should print ok.

The installer puts the relay in /opt/mangossh/relay/ and writes its .env with a new random auth token and passphrases. It starts a Caddy proxy that gets and renews the Let's Encrypt certificate, and binds port 8878 to localhost so the relay is only reachable through HTTPS. At the end it prints the Relay URL and Auth token to enter in MangoSSH.

Step 2 — Point MangoSSH at it

1. Open Settings → Remote → Relay Server.

2. Enter the Relay URL, such as wss://relay.yourteam.example, and paste the auth token the installer printed (RELAY_AUTH_TOKEN in /opt/mangossh/relay/.env) into Auth token.

3. Click Save. The row under Saved relay shows the URL and a masked token.

4. Repeat on every device that uses these features, with the same URL and token. The P2P window's Settings → Relay Server tab edits the same setting.

To test the connection, use Test next to Connect by ID — relay in the P2P window's Remote Access settings, or Test Connection in the relay step of the Set up browser access… wizard (right-click a host). Share links use the relay's address, so browsers must be able to reach it too. With a wss:// relay they get an https:// link.

Step 3 — Turn on the PAM Broker (optional)

Skip this unless you use the PAM Broker or brokered browser access. It connects the relay to your vault server, which issues short-lived signed tickets. The relay only checks the signature, so it cannot grant access by itself.

• Vault server on the same machine: nothing to do. When both bundles are installed there, the installer copies the vault server's public key into the relay's .env and restarts the relay.
• Vault server elsewhere: copy the BROKER_TRUST_PUBKEY=… line from the vault server's /opt/mangossh/vault/.env (the vault installer also prints it) into /opt/mangossh/relay/.env, then run sudo docker compose up -d in /opt/mangossh/relay.

The relay's own broker passphrase, RELAY_BROKER_CACHE_PASSPHRASE, was already generated at install. Only the public key is ever copied between machines; the private key stays on the vault server.

Configuration reference

All settings are environment variables, read from /opt/mangossh/relay/.env by Docker Compose. Run sudo docker compose up -d in that folder after changing any of them.

The three secrets can also come from files, which keeps them out of docker inspect and process listings. Set RELAY_AUTH_TOKEN_FILE, RELAY_CACHE_PASSPHRASE_FILE or RELAY_BROKER_CACHE_PASSPHRASE_FILE to a path, such as a mounted Docker secret under /run/secrets/, instead of the plain variable. The source repository's relay-server/docker-compose.yml has a commented example. Empty values count as unset, so a blank line in .env never turns off authentication.

Backups and upgrades

Two things hold state, and you need both to restore:

• /opt/mangossh/relay/.env, above all RELAY_BROKER_CACHE_PASSPHRASE. Without it, the stored credentials and recordings cannot be decrypted. Keep a copy in a password manager or safe, not next to the data backup.
• The /data volume: broker_store.json (every provisioned PAM Broker host) and rdp_recordings/. Lose it and each broker host must be provisioned again by hand.

# a compressed copy of /data from the running container
sudo docker run --rm --volumes-from mangossh-relay -v "$PWD":/backup debian:bookworm-slim \
  tar czf /backup/relay-data-$(date +%F).tgz /data

The files are already encrypted, but they are exactly what the broker passphrase unlocks, so store the archive as carefully as the passphrase. Persistent Sessions and Connect by ID pairings live only in memory and need no backup.

To upgrade, download the newer bundle and run its installer the same way. It keeps your .env and restarts the relay on the new image.

A restart drops every live relayed session and Persistent Session. Host agents reconnect by themselves. Agents running inside the app come back with a new Remote ID and password, while the Windows service keeps its own. Upgrade outside working hours.

Troubleshooting