​
title: Deployment Modes summary: local_trusted vs authenticated (private/public)

Paperclip supports two runtime modes with one authenticated exposure split.

​
local_trusted

The default mode. Optimized for single-operator local use.
  • Host binding: loopback only (localhost, 127.0.0.1, ::1)
  • Authentication: no login required
  • Use case: local development, solo experimentation
  • Board identity: local board user is auto-created
  • Trusted origins: loopback only
  • Typical env: HOST=127.0.0.1, PAPERCLIP_DEPLOYMENT_MODE=local_trusted
# Set during onboard
pnpm paperclipai onboard
# Choose "local_trusted"

​
authenticated

Login required. Supports two exposure policies.

​
authenticated + private

For private network access (Tailscale, VPN, LAN).
  • Authentication: login required via Better Auth
  • Secrets: BETTER_AUTH_SECRET required; PAPERCLIP_AGENT_JWT_SECRET remains separate for agent JWT minting
  • URL handling: PAPERCLIP_AUTH_BASE_URL_MODE=auto
  • Host binding: usually HOST=0.0.0.0
  • Host trust: private-host allowlist required for non-loopback names
  • Typical env: PAPERCLIP_DEPLOYMENT_EXPOSURE=private
pnpm paperclipai onboard
# Choose "authenticated" -> "private"
Allow custom Tailscale or LAN hostnames: 
pnpm paperclipai allowed-hostname my-machine

​
authenticated + public

For internet-facing deployment.
  • Authentication: login required
  • Secrets: BETTER_AUTH_SECRET required
  • URL: explicit public URL required
  • Security: stricter deployment checks in doctor
  • Canonical host: PAPERCLIP_PUBLIC_URL or PAPERCLIP_AUTH_PUBLIC_BASE_URL should point at the hosted origin so trusted origins can be derived deterministically
  • Host binding: usually HOST=0.0.0.0
  • Typical env: PAPERCLIP_AUTH_BASE_URL_MODE=explicit
pnpm paperclipai onboard
# Choose "authenticated" -> "public"

​
Mode Matrix

Settinglocal_trustedauthenticated + privateauthenticated + public
Human loginNoYesYes
Host bindingLoopback only0.0.0.00.0.0.0
PAPERCLIP_PUBLIC_URLOptionalRecommendedRequired
PAPERCLIP_AUTH_BASE_URL_MODEautoautoexplicit
PAPERCLIP_ALLOWED_HOSTNAMESNot neededFor Tailscale/LAN aliasesOnly for extra hostnames
Best useSolo local workPrivate-network sharingHosted production

​
Board Claim Flow

When migrating from local_trusted to authenticated, Paperclip emits a one-time claim URL at startup: 
/board-claim/<token>?code=<code>
A signed-in user visits this URL to claim board ownership. This:
  • Promotes the current user to instance admin
  • Demotes the auto-created local board admin
  • Ensures active company membership for the claiming user

​
Changing Modes

Update the deployment mode: 
pnpm paperclipai configure --section server
Runtime override via environment variable: 
PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run

​
Current Implementation Notes

  • authenticated uses Better Auth sessions and bootstrap invite flow.
  • local_trusted keeps the board operator path loopback-only and non-interactive.
  • authenticated + private derives trusted origins from the public URL and allowed hostnames.
  • authenticated + public should use HTTPS in production and an explicit canonical host.