paperclip/doc/DEPLOYMENT-MODES.md

Deployment Modes

Status: Canonical deployment and auth mode model
Date: 2026-02-23

1. Purpose

Paperclip supports two runtime modes:

1. local_trusted
2. authenticated

authenticated supports two exposure policies:

1. private
2. public

This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.

Paperclip now treats bind as a separate concern from auth:

• auth model: local_trusted vs authenticated, plus private/public
• reachability model: server.bind = loopback | lan | tailnet | custom

2. Canonical Model

Runtime Mode	Exposure	Human auth	Primary use
local_trusted	n/a	No login required	Single-operator local machine workflow
authenticated	private	Login required	Private-network access (for example Tailscale/VPN/LAN)
authenticated	public	Login required	Internet-facing/cloud deployment

Reachability Model

Bind	Meaning	Typical use
loopback	Listen on localhost only	default local usage, reverse-proxy deployments
lan	Listen on all interfaces (0.0.0.0)	LAN/VPN/private-network access
tailnet	Listen on a detected Tailscale IP	Tailscale-only access
custom	Listen on an explicit host/IP	advanced interface-specific setups

3. Security Policy

local_trusted

• loopback-only host binding
• no human login flow
• optimized for fastest local startup

authenticated + private

• login required
• low-friction URL handling (auto base URL mode)
• private-host trust policy required
• bind can be loopback, lan, tailnet, or custom

authenticated + public

• login required
• explicit public URL required
• stricter deployment checks and failures in doctor
• recommended bind is loopback behind a reverse proxy; direct lan/custom is advanced

4. Onboarding UX Contract

Default onboarding remains interactive and flagless:

pnpm paperclipai onboard

Server prompt behavior:

1. quickstart --yes defaults to server.bind=loopback and therefore local_trusted/private
2. advanced server setup asks reachability first:

• Trusted local → bind=loopback, local_trusted/private
• Private network → bind=lan, authenticated/private
• Tailnet → bind=tailnet, authenticated/private
• Custom → manual mode/exposure/host entry

3. raw host entry is only required for the Custom path
4. explicit public URL is only required for authenticated + public

Examples:

pnpm paperclipai onboard --yes
pnpm paperclipai onboard --yes --bind lan
pnpm paperclipai run --bind tailnet

configure --section server follows the same interactive behavior.

5. Doctor UX Contract

Default doctor remains flagless:

pnpm paperclipai doctor

Doctor reads configured mode/exposure and applies mode-aware checks. Optional override flags are secondary.

6. Board/User Integration Contract

Board identity must be represented by a real DB user principal for user-based features to work consistently.

Required integration points:

• real user row in authUsers for Board identity
• instance_user_roles entry for Board admin authority
• company_memberships integration for user-level task assignment and access

This is required because user assignment paths validate active membership for assigneeUserId.

7. Local Trusted -> Authenticated Claim Flow

When running authenticated mode, if the only instance admin is local-board, Paperclip emits a startup warning with a one-time high-entropy claim URL.

• URL format: /board-claim/<token>?code=<code>
• intended use: signed-in human claims board ownership
• claim action:
  • promotes current signed-in user to instance_admin
  • demotes local-board admin role
  • ensures active owner membership for the claiming user across existing companies

This prevents lockout when a user migrates from long-running local trusted usage to authenticated mode.

8. Current Code Reality (As Of 2026-02-23)

• runtime values are local_trusted | authenticated
• authenticated uses Better Auth sessions and bootstrap invite flow
• local_trusted ensures a real local Board user principal in authUsers with instance_user_roles admin access
• company creation ensures creator membership in company_memberships so user assignment/access flows remain consistent

9. Naming and Compatibility Policy

• canonical naming is local_trusted and authenticated with private/public exposure
• no long-term compatibility alias layer for discarded naming variants

10. Relationship to Other Docs

• implementation plan: doc/plans/deployment-auth-mode-consolidation.md
• V1 contract: doc/SPEC-implementation.md
• operator workflows: doc/DEVELOPING.md and doc/CLI.md