RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/doc/DEPLOYMENT-MODES.md

8.0 KiB
Raw Permalink Blame History

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
  • Better Auth request rate limiting is off by default for private mode to keep local/LAN repair loops from locking out the operator; set PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=true to opt in
  • bind can be loopback, lan, tailnet, or custom

authenticated + public

  • login required
  • explicit public URL required
  • stricter deployment checks and failures in doctor
  • Better Auth request rate limiting is on by default; set PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=false only when an explicit front-door limiter covers the deployment
  • recommended bind is loopback behind a reverse proxy; direct lan/custom is advanced
  • local stdio MCP runtime slots fail closed by default; set PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST only when a trusted worker/runtime host is configured to supervise those processes. Remote HTTP MCP remains the preferred public-hosted path.

Paperclip Cloud warm-pool identity

A Cloud-managed warm-pool process initially boots under a pool-* origin. It receives only Cloud's public verification set in PAPERCLIP_CLOUD_RUNTIME_IDENTITY_JWKS. Before Cloud activates a claimed stack, the existing server-to-server health request carries a short-lived Ed25519 JWS that binds the immutable PAPERCLIP_CLOUD_STACK_ID, pool claim, previous origin, canonical HTTPS origin, and slug. Paperclip verifies and persists that one-time assertion, updates its live public/API URL provider, and acknowledges the exact origin in /api/health before the first user request is admitted.

The Harness signing private key is never present in Paperclip, browsers, or other tenant stacks. A different claim or destination cannot replace the persisted identity. On restart, the durable identity is loaded before auth, routes, and child-runtime configuration, even when provider variables are temporarily stale. Self-hosted deployments continue to use their configured PAPERCLIP_PUBLIC_URL and do not participate in this protocol.

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
  1. raw host entry is only required for the Custom path
  2. explicit public URL is only required for authenticated + public

Examples:

pnpm paperclipai onboard --yes
npx paperclipai onboard --yes --bind lan
npx 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. First Admin Setup For Fresh Authenticated Installs

Fresh authenticated installs start in bootstrap_pending until the first instance_admin exists.

For authenticated/private, Paperclip supports a browser-first setup path:

  1. open the Paperclip URL from the private network or appliance UI
  2. sign in or create a Paperclip account
  3. choose Claim this instance on the setup screen

That browser claim promotes the signed-in session user to the first instance admin and then falls through to normal onboarding. The endpoint is available only to real browser session actors in authenticated/private; unauthenticated requests, agent keys, board API keys, and local implicit board actors are rejected.

This is intentionally a first-claim bootstrap contract: before an instance admin exists, the first authenticated browser session that completes the claim wins. Operators must keep a bootstrap_pending private deployment on a trusted network and complete setup before admitting untrusted users. This behavior is not an account-recovery or public-deployment mechanism.

The CLI fallback remains supported in all authenticated setup states:

pnpm paperclipai auth bootstrap-ceo

That command prints a one-time first-admin invite URL. Browser claim and bootstrap invite acceptance share the same first-admin transaction, so whichever path wins first makes later attempts return a conflict.

For authenticated/public, browser first-admin claim is intentionally disabled. Public deployments must use the high-entropy bootstrap invite path unless a future public-hosted setup design explicitly changes this policy.

9. 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

10. 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

11. Relationship to Other Docs

  • implementation plan: doc/plans/2026-02-23-deployment-auth-mode-consolidation.md
  • V1 contract: doc/SPEC-implementation.md
  • operator workflows: doc/DEVELOPING.md and doc/CLI.md
  • invite/join state map: doc/spec/invite-flow.md