Skip to content

The open-source app everyone uses to manage agents at work

docs: add tailscale private access guide

Dottae9ffde610ba7
diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md
index b664e13a93..874477c133 100644
--- a/docs/deploy/local-development.md
+++ b/docs/deploy/local-development.md
@@ -48,12 +48,20 @@ pnpm dev --tailscale-auth
This binds the server to `0.0.0.0` for private-network access.
+Alias:
+
+```sh
+pnpm dev --authenticated-private
+```
+
Allow additional private hostnames:
```sh
pnpm paperclipai allowed-hostname dotta-macbook-pro
```
+For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).
+
## Health Checks
```sh
diff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.md
new file mode 100644
index 0000000000..1e0d246752
--- /dev/null
+++ b/docs/deploy/tailscale-private-access.md
@@ -0,0 +1,77 @@
+---
+title: Tailscale Private Access
+summary: Run Paperclip with Tailscale-friendly host binding and connect from other devices
+---
+
+Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`.
+
+## 1. Start Paperclip in private authenticated mode
+
+```sh
+pnpm dev --tailscale-auth
+```
+
+This configures:
+
+- `PAPERCLIP_DEPLOYMENT_MODE=authenticated`
+- `PAPERCLIP_DEPLOYMENT_EXPOSURE=private`
+- `PAPERCLIP_AUTH_BASE_URL_MODE=auto`
+- `HOST=0.0.0.0` (bind on all interfaces)
+
+Equivalent flag:
+
+```sh
+pnpm dev --authenticated-private
+```
+
+## 2. Find your reachable Tailscale address
+
+From the machine running Paperclip:
+
+```sh
+tailscale ip -4
+```
+
+You can also use your Tailscale MagicDNS hostname (for example `my-macbook.tailnet.ts.net`).
+
+## 3. Open Paperclip from another device
+
+Use the Tailscale IP or MagicDNS host with the Paperclip port:
+
+```txt
+http://<tailscale-host-or-ip>:3100
+```
+
+Example:
+
+```txt
+http://my-macbook.tailnet.ts.net:3100
+```
+
+## 4. Allow custom private hostnames when needed
+
+If you access Paperclip with a custom private hostname, add it to the allowlist:
+
+```sh
+pnpm paperclipai allowed-hostname my-macbook.tailnet.ts.net
+```
+
+## 5. Verify the server is reachable
+
+From a remote Tailscale-connected device:
+
+```sh
+curl http://<tailscale-host-or-ip>:3100/api/health
+```
+
+Expected result:
+
+```json
+{"status":"ok"}
+```
+
+## Troubleshooting
+
+- Login or redirect errors on a private hostname: add it with `paperclipai allowed-hostname`.
+- App only works on `localhost`: make sure you started with `--tailscale-auth` (or set `HOST=0.0.0.0` in private mode).
+- Can connect locally but not remotely: verify both devices are on the same Tailscale network and port `3100` is reachable.
diff --git a/docs/docs.json b/docs/docs.json
index 1f3b85744f..96b9f696bd 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -73,6 +73,7 @@
"pages": [
"deploy/overview",
"deploy/local-development",
+ "deploy/tailscale-private-access",
"deploy/docker",
"deploy/deployment-modes",
"deploy/database",