docs(readme): document --relay / PIXELPASS_RELAY

Add a Relay section covering the flag and env-var forms, precedence,
the GUI-child forwarding, and the same-relay-on-both-ends requirement.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -223,6 +223,25 @@ measured_at = "2026-05-21T20:41:16Z"
 - Skip is sticky — once you skip the test, pixelpass won't ask again
   unless you reconfigure.
 
+## Relay
+
+By default pixelpass uses iroh's bundled relay servers to coordinate the
+P2P connection (peers still hole-punch a direct UDP path when they can; the
+relay is the fallback and the rendezvous point). You can point it at a
+different relay — a self-hosted one, or n0's staging/production servers —
+with either:
+
+```bash
+pixelpass --relay https://relay.example/            # host or viewer
+PIXELPASS_RELAY=https://relay.example/ pixelpass …  # env-var form
+```
+
+The flag applies to both host and viewer and takes precedence over the
+environment variable. The env-var form is handy for the `--gui` front-end,
+since the GUI's child host/viewer processes inherit it; the `--gui --relay`
+flag form is forwarded to them too. Both ends must use the same relay to
+find each other.
+
 ## Audio
 
 By default pixelpass captures the default sink's monitor — the viewer

src/common/deps.rs

@@ -85,20 +85,20 @@ fn install_hint_for_bin(bin: &str) -> String {
     let distro = detect_distro();
     let pkg = match bin {
         "gst-launch-1.0" | "gst-inspect-1.0" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gstreamer gst-plugins-base",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gstreamer gst-plugins-base",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-tools",
             Some("fedora" | "nobara") => "gstreamer1 gstreamer1-plugins-base-tools",
             _ => "gstreamer + tools",
         },
         "pactl" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "libpulse",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "libpulse",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "pulseaudio-utils",
             Some("fedora" | "nobara") => "pulseaudio-utils",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "pulseaudio-utils",
             _ => "pulseaudio-utils (provides `pactl`)",
         },
         "xwininfo" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "xorg-xwininfo",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "xorg-xwininfo",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "x11-utils",
             Some("fedora" | "nobara") => "xorg-x11-utils",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "xwininfo",
@@ -113,56 +113,56 @@ fn install_hint_for_gst_element(name: &str) -> String {
     let distro = detect_distro();
     let pkg = match name {
         "pipewiresrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugin-pipewire",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugin-pipewire",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-pipewire",
             Some("fedora" | "nobara") => "pipewire-gstreamer",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "pipewire-gstreamer",
             _ => "the GStreamer PipeWire plugin",
         },
         "vah264enc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugin-va",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugin-va",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-bad",
             Some("fedora" | "nobara") => "gstreamer1-plugins-bad-free",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-bad",
             _ => "the GStreamer VA-API plugin (requires an H.264-capable GPU; almost all modern GPUs)",
         },
         "x264enc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-ugly",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-ugly",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-ugly",
             Some("fedora" | "nobara") => "gstreamer1-plugins-ugly",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-ugly",
             _ => "the GStreamer x264 plugin (plugins-ugly)",
         },
         "ximagesrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-good",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-good",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-good",
             Some("fedora" | "nobara") => "gstreamer1-plugins-good",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-good",
             _ => "the GStreamer X11 plugin (plugins-good)",
         },
         "videoscale" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-base",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-base",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-base",
             Some("fedora" | "nobara") => "gstreamer1-plugins-base",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-base",
             _ => "the GStreamer plugins-base set",
         },
         "h264parse" | "mpegtsmux" | "aacparse" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-bad",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-bad",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-plugins-bad",
             Some("fedora" | "nobara") => "gstreamer1-plugins-bad-free",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-bad",
             _ => "the GStreamer plugins-bad set",
         },
         "pulsesrc" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-plugins-good",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-plugins-good",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-pulseaudio",
             Some("fedora" | "nobara") => "gstreamer1-plugins-good",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-plugins-good",
             _ => "the GStreamer PulseAudio plugin",
         },
         "avenc_aac" => match distro.as_deref() {
-            Some("arch" | "cachyos" | "manjaro" | "endeavouros") => "gst-libav",
+            Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => "gst-libav",
             Some("debian" | "ubuntu" | "pop" | "linuxmint") => "gstreamer1.0-libav",
             Some("fedora" | "nobara") => "gstreamer1-libav",
             Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => "gstreamer-libav",
@@ -175,7 +175,7 @@ fn install_hint_for_gst_element(name: &str) -> String {
 
 fn install_command(distro: &Option<String>, pkg: &str) -> String {
     let cmd = match distro.as_deref() {
-        Some("arch" | "cachyos" | "manjaro" | "endeavouros") => format!("sudo pacman -S {pkg}"),
+        Some("arch" | "cachyos" | "manjaro" | "endeavouros" | "artix" | "garuda") => format!("sudo pacman -S {pkg}"),
         Some("debian" | "ubuntu" | "pop" | "linuxmint") => format!("sudo apt install {pkg}"),
         Some("fedora" | "nobara") => format!("sudo dnf install {pkg}"),
         Some("opensuse" | "opensuse-tumbleweed" | "opensuse-leap") => format!("sudo zypper install {pkg}"),

src/gui/mod.rs

@@ -584,7 +584,11 @@ impl ApplicationHandler<UserEvent> for App {
 /// Launch the GUI. Blocks until the window is closed (or the tray Quit is
 /// chosen). Runs on the main thread, a winit requirement, which is where `main`
 /// calls it from.
-pub fn run() -> anyhow::Result<()> {
+/// `relay` is the parent's `--relay` flag (if any), forwarded to every child
+/// process so a relay chosen on the GUI command line reaches the headless
+/// host/viewer. (The `PIXELPASS_RELAY` env var is inherited regardless; this
+/// covers the flag form.)
+pub fn run(relay: Option<String>) -> anyhow::Result<()> {
     let event_loop = EventLoop::<UserEvent>::with_user_event()
         .build()
         .map_err(|e| anyhow::anyhow!("failed to build the event loop: {e}"))?;
@@ -607,6 +611,7 @@ pub fn run() -> anyhow::Result<()> {
         tray,
         close_to_tray: gui_settings.close_to_tray,
         show_qr: gui_settings.show_qr,
+        relay,
         waker,
     };
     let mut app = App {
@@ -845,6 +850,9 @@ struct PixelPassApp {
     /// Persisted preference: render the QR-code panel on the host screen.
     /// Defaults to on; toggled in Settings.
     show_qr: bool,
+    /// The parent's `--relay` flag, forwarded to host/viewer children so the
+    /// flag form reaches them (env-var form is inherited automatically).
+    relay: Option<String>,
     /// Wakes the winit loop when a spawned child emits/exits.
     waker: Waker,
 }
@@ -1230,6 +1238,10 @@ impl PixelPassApp {
         if self.host.window {
             args.push("--window".to_string());
         }
+        if let Some(relay) = &self.relay {
+            args.push("--relay".to_string());
+            args.push(relay.clone());
+        }
 
         match ChildProc::spawn(&args, self.waker.clone()) {
             Ok(p) => self.host.proc = Some(p),
@@ -1503,7 +1515,11 @@ impl PixelPassApp {
 
         let ticket = self.viewer.ticket_input.trim().to_string();
         self.viewer.connecting_to = ticket_endpoint_id(&ticket).map(|id| short_id(&id));
-        let args = vec![ticket, "--output".to_string(), "json".to_string()];
+        let mut args = vec![ticket, "--output".to_string(), "json".to_string()];
+        if let Some(relay) = &self.relay {
+            args.push("--relay".to_string());
+            args.push(relay.clone());
+        }
         match ChildProc::spawn(&args, self.waker.clone()) {
             Ok(p) => self.viewer.proc = Some(p),
             Err(e) => self.viewer.error = Some(format!("Couldn't connect: {e}")),

src/main.rs

@@ -25,7 +25,7 @@ async fn main() -> Result<()> {
     if cli.gui {
         #[cfg(feature = "gui")]
         {
-            return gui::run();
+            return gui::run(cli.relay);
         }
         #[cfg(not(feature = "gui"))]
         {