Run your own relay

Remote sessions work with Connecto's relay out of the box. If you would rather not depend on it, run your own on any small server and point your machines at it.

The relay is the standard iroh-relay server from the iroh project, unmodified. It helps two machines find each other and carries their traffic when they cannot connect directly. Everything that passes through it is encrypted end to end between your machines, so the relay cannot read it.

Which version to run

Run the iroh-relay version that matches the iroh library your Connecto is built with.

To check a build yourself, look for name = "iroh-relay" in the Cargo.lock of the source you built from.

What you need

• A server with a public IP address. A small Linux VPS is plenty (1 vCPU, 512 MB of RAM). The examples here use Ubuntu or Debian with systemd.
• A DNS name pointing at it, for example relay.example.com (an A record, and AAAA if you have IPv6).
• Open ports: TCP 80 and 443, and UDP 7842. UDP 7842 is for QUIC address discovery, which helps the machines find a direct path. It must stay 7842, because Connecto takes only the host name from the relay address and uses the default port for this.
• Rust (stable, from rustup.rs), to build the relay. You can build on another machine with the same OS and CPU type and copy the binary across.

1. Build the relay

cargo install iroh-relay@1.4.1 --locked --features server

This builds and installs the binary as ~/.cargo/bin/iroh-relay. Then install it system-wide and give it a user of its own:

sudo install -m 755 ~/.cargo/bin/iroh-relay /usr/local/bin/iroh-relay
sudo useradd --system --home /var/lib/iroh-relay --create-home --shell /usr/sbin/nologin iroh-relay
sudo mkdir -p /etc/iroh-relay

2. Make an access token

Without a token, anyone who finds your relay can use it. Make a long random one:

openssl rand -base64 32 | tr -d '/+=' | head -c 40; echo

Keep it somewhere safe, like a password manager. You will enter it once on each of your machines. Builds of Connecto carry no token for a relay of your own: you always add it yourself.

3. Configure it

Choose one of the two ways to handle TLS below. Both need a certificate on the relay itself, because the QUIC address discovery on UDP 7842 does its own TLS.

Option A: the relay handles TLS itself (simplest)

Use this when nothing else on the server uses ports 80 and 443. The relay gets and renews its own Let's Encrypt certificate.

/etc/iroh-relay/config.toml:

enable_relay = true
http_bind_addr = "[::]:80"
enable_quic_addr_discovery = true
enable_metrics = false

access.shared_token = ["PASTE-YOUR-TOKEN-HERE"]

[tls]
cert_mode = "LetsEncrypt"
hostname = "relay.example.com"
contact = "you@example.com"
cert_dir = "/var/lib/iroh-relay/certs"
# https_bind_addr defaults to port 443, quic_bind_addr to UDP 7842

Option B: behind a reverse proxy you already run

Use this when Caddy, nginx or another server already owns port 443. The relay listens on a local port, and the proxy forwards to it. The relay still needs the certificate files for QUIC. Point it at a copy of the proxy's certificate for the same host name, and use Reloading so it picks up renewals without a restart.

enable_relay = true
http_bind_addr = "127.0.0.1:8080"
enable_quic_addr_discovery = true
enable_metrics = false

access.shared_token = ["PASTE-YOUR-TOKEN-HERE"]

[tls]
cert_mode = "Reloading"
https_bind_addr = "127.0.0.1:8443"
quic_bind_addr = "[::]:7842"
manual_cert_path = "/etc/iroh-relay/certs/relay.crt"
manual_key_path = "/etc/iroh-relay/certs/relay.key"

Copy the proxy's certificate and key for relay.example.com to those two paths. The files must be readable by the iroh-relay user. Copy them again after each renewal, with a cron job or a systemd timer. The relay serves WebSocket upgrades on /relay, so the proxy must pass them through.

Caddy (it passes upgrades by default):

relay.example.com {
    reverse_proxy https://127.0.0.1:8443 {
        transport http {
            tls_server_name relay.example.com
        }
    }
}

nginx:

server {
    listen 443 ssl;
    server_name relay.example.com;
    ssl_certificate     /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    location / {
        proxy_pass https://127.0.0.1:8443;
        proxy_ssl_server_name on;
        proxy_ssl_name relay.example.com;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 1h;
    }
}

UDP 7842 does not go through the proxy: open it in the firewall and let it reach the relay directly.

4. Run it as a service

/etc/systemd/system/iroh-relay.service:

[Unit]
Description=iroh relay for Connecto
After=network-online.target
Wants=network-online.target

[Service]
User=iroh-relay
Group=iroh-relay
WorkingDirectory=/var/lib/iroh-relay
ExecStart=/usr/local/bin/iroh-relay --config-path /etc/iroh-relay/config.toml
Restart=always
RestartSec=5
# Needed only for option A, which binds ports 80 and 443:
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now iroh-relay
sudo journalctl -u iroh-relay -f

Open the ports, for example with ufw: sudo ufw allow 80/tcp, sudo ufw allow 443/tcp, sudo ufw allow 7842/udp. Many hosting providers also have a firewall of their own, so open the ports there too.

Check it

curl -fsS https://relay.example.com/healthz

This should answer with HTTP 200. Opening https://relay.example.com/ in a browser shows the relay's own page.

5. Point Connecto at it

Do this on every machine you use with remote sessions. Pairing and connecting find the other machine through the relay, so both sides must use the same one.

1. Open Settings and find RELAY.
2. Set the address to https://relay.example.com. Use the bare host name, with no port and no path.
3. Paste your token into the access token field.
4. Click Save relay. The section then says Access token set.

The token is kept with Connecto's other secrets, in a file only your account can read (see Where secrets are kept), never in a settings file. Connecto's own built-in token is sent only to https://relay.connecto.studio, never to a relay of yours. If you see "Could not reach the relay", check the address, the token and that ports 443 and 7842 are open.

To go back to Connecto's relay, set the address to https://relay.connecto.studio and click Remove saved token. To use no relay at all, leave the address empty: only direct connections are tried then.

Changing the token

access.shared_token takes a list, so you can rotate a token without downtime:

1. Add the new token next to the old one: access.shared_token = ["OLD", "NEW"], then run sudo systemctl restart iroh-relay.
2. Enter the new token on each machine.
3. Remove the old token from the list and restart the relay again.

The relay has no other way to revoke a token: you edit the list and restart the service.

Upgrading the relay

1. Check the table at the top of this page, or the release notes, for the iroh-relay version the new Connecto needs. If it is the same as yours, there is nothing to do.
2. Build the new version: cargo install iroh-relay@NEW_VERSION --locked --features server.
3. Install it and restart: sudo install -m 755 ~/.cargo/bin/iroh-relay /usr/local/bin/iroh-relay, then sudo systemctl restart iroh-relay.
4. Check it: curl -fsS https://relay.example.com/healthz and journalctl -u iroh-relay.

Connected sessions drop during the restart and reconnect by themselves. Keep the old binary until the new one has run for a while (sudo cp /usr/local/bin/iroh-relay /usr/local/bin/iroh-relay.prev before step 3), so you can go back by copying it into place again.