docs: add connectivity guide
This commit is contained in:
Mohamed Boudra
@@ -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
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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`:
|
||||
|
||||
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user