Self-host a Relay Node

Codux Mobile pairs with the desktop over the Iroh transport. It prefers a direct peer-to-peer path; a relay is only used to help the two devices find each other and to carry traffic when a direct path is unavailable. The desktop app is always the real terminal host, and the relay never sees your decrypted content.

For most people the relay is just a choice in Settings → Remote — no address to manage:

Option	When to use
Global	The default. Works out of the box.
China (Tencent Cloud) / China (Alibaba Cloud)	A faster path for users in China. Built in — just select it.
Custom	Your own relay node (below).

When to run your own relay

• Your phone and desktop are often on networks where the public path is slow or blocked.
• You want pairing/connection metadata to stay on infrastructure you control.
• You want a relay close to your users for lower latency.

Deploy a private Iroh relay

A Codux relay is a standard Iroh relay — Codux uses iroh 1.0, so run a matching relay version.

1. Get a host and a domain. The relay must be reachable over HTTPS, so you need a public server and a domain name (e.g. relay.example.com) with TLS. Iroh relays terminate TLS themselves (Let’s Encrypt or your own certificate).
2. Run the iroh-relay server. Install it from the Iroh project (cargo install iroh-relay, or use a prebuilt binary), write a relay config that sets your hostname and TLS, and start it. Follow the official Iroh relay documentation for the exact config and flags for your iroh version.
3. Open the port. Expose HTTPS (port 443) so clients can reach https://relay.example.com.

The relay does not need any Codux-specific software — it is plain Iroh relay infrastructure.

Register the relay in Codux

On the desktop app:

1. Open Codux → Settings → Remote.
2. Set the relay to Custom and enter your Custom Relay URL, e.g. https://relay.example.com.
3. If your relay requires a bearer token, fill in Relay Authentication.
4. Pair the mobile client again so the QR code reflects the new path.

That’s it — the phone will now reach the desktop through your own relay when a direct connection isn’t possible.

What the relay does not do

• It does not run your terminal — the desktop stays the host.
• It does not store AI sessions, memory, or project files.
• It does not see decrypted terminal content; traffic is end-to-end encrypted over Iroh’s QUIC connection.