PaperClipAI/docs/deploy/deployment-modes.md at 98df214917bc8f8a70b63b58105a1deea7cd73b0

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-26 02:00:52 +01:00

Files

T

Harold KimandPaperclip 98df214917 fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-07-09 10:08:57 +00:00

2.1 KiB

Raw Blame History

title, summary

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

Paperclip supports two runtime modes with different security profiles. Reachability is configured separately with bind.

`local_trusted`

The default mode. Optimized for single-operator local use.

Host binding: loopback only (localhost)
Bind: loopback
Authentication: no login required
Use case: local development, solo experimentation
Board identity: auto-created local board user

# Set during onboard
pnpm paperclipai onboard
# Choose "local_trusted"

`authenticated`

`authenticated` + `private`

For private network access (Tailscale, VPN, LAN).

Authentication: login required via Better Auth
URL handling: auto base URL mode (lower friction)
Host trust: private-host trust policy required
Bind: choose loopback, lan, tailnet, or custom

pnpm paperclipai onboard
# Choose "authenticated" -> "private"

Allow custom Tailscale hostnames:

pnpm paperclipai allowed-hostname my-machine

`authenticated` + `public`

For internet-facing deployment.

Authentication: login required
URL: explicit public URL required
Security: stricter deployment checks in doctor
Bind: usually loopback behind a reverse proxy; lan/custom is advanced

pnpm paperclipai onboard
# Choose "authenticated" -> "public"

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 PAPERCLIP_BIND=lan pnpm paperclipai run

2.1 KiB Raw Blame History

local_trusted

authenticated

authenticated + private

authenticated + public