From f2a23039cb3c730f8c6e476f0e754fea1a52f21f Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Fri, 1 May 2026 21:06:08 +0700
Subject: [PATCH] docs: document password authentication in public docs

---
 public-docs/configuration.md | 43 ++++++++++++++++++++++++++++++++++++
 public-docs/security.md      | 24 +++++++++++++++++++-
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/public-docs/configuration.md b/public-docs/configuration.md
index d505d29c4..addae4457 100644
--- a/public-docs/configuration.md
+++ b/public-docs/configuration.md
@@ -89,9 +89,52 @@ Daemon logging uses separate console and file sinks by default:
 
 Legacy fields `log.level` and `log.format` are still supported and map to the new destination settings.
 
+## Password authentication
+
+You can require a password to connect to the daemon. When set, all HTTP and WebSocket clients must authenticate — except the health and status endpoints (`/api/health`, `/api/status`).
+
+The easiest way to set a password is with the CLI:
+
+```bash
+paseo daemon set-password
+```
+
+This prompts for a password, writes the bcrypt hash to `config.json`, and tells you to restart the daemon.
+
+Alternatively, set the `PASEO_PASSWORD` environment variable (plaintext — hashed automatically at startup):
+
+```bash
+PASEO_PASSWORD=my-secret paseo daemon start
+```
+
+Or write the hash directly in `config.json`:
+
+```json
+{
+  "daemon": {
+    "auth": {
+      "password": "$2b$12$..."
+    }
+  }
+}
+```
+
+After setting a password, restart the daemon for the change to take effect.
+
+### Connecting with a password
+
+The CLI reads the password from the TCP URI automatically:
+
+```bash
+paseo --host "tcp://192.168.1.10:6767?password=my-secret" ls
+```
+
+In the mobile app, enter the password in the direct connection setup screen.
+
 ## Common env vars
 
 - `PASEO_HOME` — set Paseo home directory
+- `PASEO_PASSWORD` — require a password to connect (plaintext, hashed at startup)
 - `PASEO_LISTEN` — override `daemon.listen`
 - `PASEO_HOSTNAMES` — override/extend `daemon.hostnames`
 - `PASEO_ALLOWED_HOSTS` — deprecated alias for `PASEO_HOSTNAMES`
diff --git a/public-docs/security.md b/public-docs/security.md
index 38b6e6684..d1e2067d3 100644
--- a/public-docs/security.md
+++ b/public-docs/security.md
@@ -85,6 +85,27 @@ Configure via `daemon.hostnames` in `config.json`:
 - `['.example.com']`: allow `example.com` and any subdomain, plus defaults
 - `true`: allow any host (not recommended)
 
+## Password authentication
+
+By default, anyone who can reach the daemon's listening address can connect. On localhost this is fine — only local processes have access. But if you bind to a network interface (e.g. your LAN IP or `0.0.0.0`), or if you don't fully trust your local network, you can require a password.
+
+When a password is configured, all HTTP requests must include an `Authorization: Bearer <password>` header and all WebSocket connections must authenticate via subprotocol. Unauthenticated requests receive a `401 Unauthorized` response. The `/api/health` and `/api/status` endpoints are exempt so that health probes and process supervisors continue to work without credentials.
+
+The password is stored as a bcrypt hash in `config.json` — the daemon never stores it in plaintext. See [Configuration](/docs/configuration#password-authentication) for setup instructions.
+
+### What password auth does and does not do
+
+- **Does:** Prevents unauthorized clients from controlling your agents, even if they can reach the daemon over the network.
+- **Does not:** Encrypt traffic. Password auth protects access, not confidentiality. If you need encrypted connections over an untrusted network, use the relay (which provides end-to-end encryption) or a VPN like Tailscale.
+
+### When to use it
+
+- You want to bind the daemon to a LAN or Tailscale address and restrict who can connect.
+- You don't fully trust your local network (shared office, public Wi-Fi with a VPN, etc.).
+- You're exposing the daemon via a reverse proxy and want an additional authentication layer.
+
+We still recommend the relay for mobile access — it combines authentication with end-to-end encryption out of the box. Password auth is primarily useful for direct LAN or VPN connections where you want access control without the relay.
+
 ## Agent authentication
 
 Paseo wraps agent CLIs (Claude Code, Codex, OpenCode) but does not manage their authentication. Each agent provider handles its own credentials:
@@ -99,5 +120,6 @@ Paseo never stores or transmits provider API keys. Agents run in your user conte
 
 - **Use the relay** for mobile access — it's the simplest option and all traffic is end-to-end encrypted
 - **Treat the QR code like a password** — anyone with the pairing offer can connect to your daemon
-- **Never bind to 0.0.0.0** unless you understand the implications and have proper firewall rules
+- **Set a password** if you bind to a network address — it prevents unauthorized clients from controlling your agents
+- **Never bind to 0.0.0.0 without a password** — without one, any device on your network can connect
 - **Keep your daemon updated** — security improvements are released regularly