Tailscale Private Access

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

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)
BETTER_AUTH_SECRET must still be set for board/session auth; it is separate from PAPERCLIP_AGENT_JWT_SECRET

Equivalent flag:

pnpm dev --authenticated-private

From the machine running Paperclip:

tailscale ip -4

You can also use your Tailscale MagicDNS hostname (for example my-macbook.tailnet.ts.net).

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

If you access Paperclip with a custom private hostname, add it to the allowlist:

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

From a remote Tailscale-connected device:

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

Expected result:

{"status":"ok"}

Login or redirect errors on a private hostname: add it with paperclipai allowed-hostname.
Auth startup failures in authenticated mode: verify BETTER_AUTH_SECRET is present and not being confused with the agent JWT secret.
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.