PaperClipAI/docs/deploy/tailscale-private-access.md

title, summary

title	summary
Tailscale Private Access	Run Paperclip with Tailscale-friendly bind presets and connect from other devices

Use this for first-time operator setup when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only localhost.

Existing managed host: if Tailscale and Paperclip are already running, reuse the current service and advertised URL. Do not run these setup steps, modify Tailscale Serve, request an operator grant, or issue a certificate as part of ordinary feature, QA, or package-preview work. Those are separate operator-owned topology changes and must be explicitly requested by the task.

1. Start Paperclip in private authenticated mode

pnpm dev --bind tailnet

Recommended behavior:

• PAPERCLIP_DEPLOYMENT_MODE=authenticated
• PAPERCLIP_DEPLOYMENT_EXPOSURE=private
• PAPERCLIP_BIND=tailnet

If you want the old broad private-network behavior instead, use:

pnpm dev --bind lan

Legacy aliases still map to authenticated/private + bind=lan:

pnpm dev --authenticated-private
pnpm dev --tailscale-auth

2. Find your reachable Tailscale address

From the machine running Paperclip:

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:

http://<tailscale-host-or-ip>:3100

Example:

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:

npx paperclipai allowed-hostname my-macbook.tailnet.ts.net

5. Verify the server is reachable

From a remote Tailscale-connected device:

curl http://<tailscale-host-or-ip>:3100/api/health

Expected result:

{"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 --bind lan or --bind tailnet instead of plain pnpm dev.
• Can connect locally but not remotely: verify both devices are on the same Tailscale network and port 3100 is reachable.