docs: add connectivity guide

2026-08-04 00:42:34 +02:00
parent 3a9d39b63a
commit 74dea38456
7 changed files with 103 additions and 12 deletions
@@ -0,0 +1,92 @@
+---
+title: Connectivity
+description: Connect a Paseo client to your daemon through the relay or Tailscale.
+nav: Connectivity
+order: 4
+category: Getting started
+---
+
+# Connectivity
+
+Your Paseo app connects to the daemon running on your computer or server. You can connect through the Paseo relay or directly with Tailscale.
+
+- [Paseo relay](#paseo-relay)
+- [Tailscale](#tailscale)
+
+## Paseo relay
+
+The relay works without Tailscale, port forwarding, or network configuration. Traffic is end-to-end encrypted.
+
+Relay is disabled until you enable it.
+
+### Enable relay from Paseo Desktop
+
+1. Open **Settings → your host → Pair a device**.
+2. Select **Enable relay**.
+3. Scan the QR code with Paseo on your phone, or copy the pairing link and paste it into the phone app.
+
+### Enable relay from the CLI
+
+Run:
+
+```bash
+paseo daemon pair
+```
+
+Confirm when prompted. Paseo prints a QR code and pairing link. Scan the QR code with Paseo on your phone, or choose **Paste pairing link** in the phone app.
+
+## Tailscale
+
+Install [Tailscale](https://tailscale.com/download) on the daemon machine and your phone. Sign in to the same tailnet on both devices.
+
+### 1. Find the daemon machine's Tailscale IP
+
+Run this on the daemon machine:
+
+```bash
+tailscale ip -4
+```
+
+Copy the address it prints. The example below uses `100.101.102.103`.
+
+### 2. Configure the daemon
+
+Open `~/.paseo/config.json` and set `daemon.listen` to the Tailscale IP:
+
+```json
+{
+  "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
+  "version": 1,
+  "daemon": {
+    "listen": "100.101.102.103:6767"
+  }
+}
+```
+
+Keep the other settings already in the file. If it has a `daemon` object, add `listen` inside that object.
+
+To restrict access with a password, see [Password authentication](/docs/configuration#password-authentication).
+
+Restart the daemon:
+
+```bash
+paseo daemon restart
+```
+
+If Paseo Desktop manages the daemon, use **Settings → your host → Overview → Restart daemon**.
+
+### 3. Connect the phone app
+
+1. Connect Tailscale on your phone.
+2. Open Paseo and go to **Settings → Add host → Direct connection**.
+3. Enter the Tailscale IP in **Host**.
+4. Enter `6767` in **Port**.
+5. Leave **Use SSL** off and select **Connect**.
+
+If the host was already paired through the relay, Paseo adds the direct connection to the same host.
+
+## Troubleshooting
+
+- **Connection timed out:** Check that Tailscale is connected on both devices and that you used the daemon machine's Tailscale IP.
+- **Connection refused:** Run `paseo daemon status` and confirm the daemon is running on the configured IP and port.
+- **Config change has no effect:** Restart the daemon after editing `config.json`.