diff --git a/README.md b/README.md index 1d51c67fa..07c02012c 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,7 @@ Paseo starts locally, then asks whether to enable the end-to-end encrypted relay For full setup and configuration, see: - [Docs](https://paseo.sh/docs) +- [Connectivity guide](https://paseo.sh/docs/connectivity) - [Configuration reference](https://paseo.sh/docs/configuration) ### Docker diff --git a/packages/website/src/styles.css b/packages/website/src/styles.css index 0f779936c..26414258a 100644 --- a/packages/website/src/styles.css +++ b/packages/website/src/styles.css @@ -307,9 +307,11 @@ .docs-prose h2 { color: var(--color-foreground); - font-size: 1.25rem; + font-size: 1.375rem; line-height: 1.4; font-weight: 500; + padding-bottom: 0.5rem; + border-bottom: 1px solid var(--color-border); margin-top: 2rem; margin-bottom: 1rem; } diff --git a/public-docs/configuration.md b/public-docs/configuration.md index 474d5ff9b..562981f2d 100644 --- a/public-docs/configuration.md +++ b/public-docs/configuration.md @@ -189,7 +189,7 @@ In the mobile app, enter the password in the direct connection setup screen. ## Relay -New homes write `daemon.relay.enabled: false`. Paseo asks before enabling relay when you pair a device; existing homes keep their saved value. See [Security](/docs/security) for relay encryption and direct connection alternatives. +New homes write `daemon.relay.enabled: false`. Paseo asks before enabling relay when you pair a device; existing homes keep their saved value. See [Connectivity](/docs/connectivity) to choose and configure a connection method, and [Security](/docs/security) for the relay encryption model. Set the persisted value in `config.json`: diff --git a/public-docs/connectivity.md b/public-docs/connectivity.md new file mode 100644 index 000000000..371e3808b --- /dev/null +++ b/public-docs/connectivity.md @@ -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`. diff --git a/public-docs/index.md b/public-docs/index.md index b092e5cd7..c5786f870 100644 --- a/public-docs/index.md +++ b/public-docs/index.md @@ -50,6 +50,7 @@ The image runs the daemon and serves the bundled web UI. It does not bundle agen ## Where next +- [Connectivity](/docs/connectivity), connect through the relay or Tailscale. - [Docker](/docs/docker), run the daemon and bundled web UI in a container. - [Workspaces](/docs/workspaces), the project, workspace, and session model Paseo is built around. - [Providers](/docs/providers), what a provider is and how Paseo wraps existing CLIs. diff --git a/public-docs/security.md b/public-docs/security.md index 4b58dc112..16bf086b5 100644 --- a/public-docs/security.md +++ b/public-docs/security.md @@ -2,7 +2,7 @@ title: Security description: "Security model for Paseo: architecture overview, connection methods, relay encryption, and best practices." nav: Security -order: 4 +order: 5 category: Getting started --- @@ -58,20 +58,15 @@ If you believe a pairing offer has been compromised, restart the daemon to gener By default, the daemon listens on `127.0.0.1:6767` (localhost only). This is safe for local CLI usage but not reachable from your phone or other devices. +For relay and Tailscale setup instructions, see [Connectivity](/docs/connectivity). + ### Socket file (CLI only) For maximum isolation, you can configure the daemon to listen on a Unix socket file instead of a TCP port. This prevents any network access entirely, only processes on the same machine can connect. The CLI supports this mode, but the mobile app and web interface require a network connection. ### VPN access -If you prefer direct connections over the relay, you can use a VPN like [Tailscale](https://tailscale.com). Tailscale creates a private network between your devices, so you can access your daemon without exposing it to the public internet. - -To set this up: - -1. Install Tailscale on your machine and phone and join them to the same [tailnet](https://tailscale.com/kb/1136/tailnet) -2. Configure the daemon to listen on your Tailscale IP (e.g., `100.x.y.z:6767`) -3. Add your Tailscale hostname to `hostnames` and `cors.allowedOrigins` -4. Add the daemon as a direct connection in the Paseo app using the Tailscale address +Use a VPN such as [Tailscale](https://tailscale.com) when you want a direct connection outside your local network. The VPN encrypts the traffic and keeps the daemon off the public internet. Bind the daemon to its VPN address, set a Paseo password, then add that address as a direct connection in the client. ### Binding to 0.0.0.0 diff --git a/public-docs/web-ui.md b/public-docs/web-ui.md index 445b1eb19..fd2628ed9 100644 --- a/public-docs/web-ui.md +++ b/public-docs/web-ui.md @@ -63,7 +63,7 @@ The same HTTP server keeps serving the API (`/api/*`), MCP (`/mcp/*`), service-p Three common ways to run it, in order of exposure: - **Same machine.** Daemon and browser on one box. Open `http://localhost:6767/`. Nothing else to configure. -- **Private network (LAN or VPN).** Reach the daemon from other devices on a network you trust, a home LAN or a [Tailscale](https://tailscale.com) tailnet. Bind the daemon to that interface and connect to it by address. +- **Private network (LAN or VPN).** Reach the daemon from other devices on a network you trust, a home LAN or a [Tailscale](https://tailscale.com) tailnet. Follow the [Connectivity guide](/docs/connectivity#tailscale) for the complete direct setup. - **Public reverse proxy or tunnel.** Expose the UI on a domain over HTTPS, terminating TLS at a reverse proxy or a tunnel. This is the full self-hosted setup. The rest of this page builds from local to public. **Verify a direct connection works before you add a proxy in front of it**, it isolates daemon problems from proxy problems.