## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - In `local_trusted` mode, the operator's own local processes get implicit board access without credentials > - #21181 added a local board boundary. It refuses implicit board access to requests that come from an agent run's process tree > - On Linux CI hosts, the boundary sometimes did not decide a loopback request. It logged a warning and kept the earlier permissive behavior for that request > - The cause was not IPv6. IPv4 and IPv6 loopback lookups worked. The gap was a connection that belonged to a same-user process that the server cannot inspect > - This pull request makes the Linux boundary decide those connections from the process ancestry that the server can read, and refuse them when that ancestry is not clearly the operator's > - The benefit is that the local board boundary now holds on Linux for IPv4 and IPv6 loopback, and the operator's browser and CLI keep working ## Linked Issues or Issue Description Refs #21181 **What happened?** On Linux CI hosts, the local board boundary sometimes could not attribute a loopback request to a process. It then logged that it could not identify the local process and kept the earlier permissive behavior for that request. In one chat eval cohort, 37 of 191 server logs contained this warning. The warning is logged once per server process. **Expected behavior** The boundary decides every uncredentialed loopback request on Linux. A request from an agent run gets no implicit board access. Requests from the operator's browser and CLI keep implicit board access. **Actual behavior** Some requests on Linux were not decided by the boundary, and they got implicit board access. ## What Changed - The Linux inspector now records which same-user processes it cannot inspect. Before, it only recorded that one existed. - The Linux TCP table lookup now also returns the socket's owner UID. It covers `/proc/net/tcp` and `/proc/net/tcp6`, including IPv4-mapped addresses. - If no inspectable process owns the connection, the server reads the TCP tables again. If the connection is gone, has changed, or belongs to a different user, the request is refused. - If the connection is still open and same-user, the server checks every process it cannot inspect. Implicit board access stays only if each one has a readable parent chain that does not belong to an agent run. Otherwise the request is refused. - The "cannot identify" fallback now applies only when the platform has no inspector, or when Linux cannot read the TCP tables. The server keeps logging a warning in that case. - `doc/DEPLOYMENT-MODES.md` describes the new Linux behavior. **How the operator is recognized** - Browser and CLI processes are normal same-user processes. The server reads their open sockets and environment, so their requests are classified as before. - A browser helper process that the server cannot inspect is still the operator when its readable parent chain leads to the browser and has no agent-run markers. - The server's own requests and requests from the server's ancestors stay the operator, as before. - Connections owned by other users were refused before, and they are still refused. ## Verification - `pnpm --dir server exec vitest run src/__tests__/local-agent-process-boundary.test.ts` passes on macOS (15 passed, 10 Linux-only skipped). - The same file ran on Linux (Docker, `node:24-bookworm`, non-root user, IPv6 loopback on). Result: 25 passed. - Red check on Linux with the previous boundary and the new tests: the agent-run cases for processes the server cannot inspect failed for both `127.0.0.1` and `::1`. The operator cases passed. - New Linux-only tests run real processes over `127.0.0.1` and `::1`: - an operator process keeps board access - an agent-run process is refused - an operator process the server cannot inspect keeps board access - an agent-run process the server cannot inspect is refused - New platform-independent tests cover the classification rules and the `/proc/net/tcp6` fixture parsing. - A paid chat-feature run on Linux CI, with temporary diagnostic logging on a separate branch, checks the server logs for the warning and for refused operator requests. The results will be in a PR comment. ## Risks - A rare operator tool that the server cannot inspect, and whose parent chain the server cannot read, now loses implicit board access. Such a tool can use a board API key. - The extra TCP table read happens only when a connection has no inspectable owner. Normal requests do no extra work. - Platforms without process inspection keep the previous behavior. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, Docker on Linux) and extended reasoning. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Deployment Modes
Status: Canonical deployment and auth mode model
Date: 2026-02-23
Paperclip Cloud sign-in
Cloud-managed instances use Cloud for human sign-in. The instance /auth
route waits for deployment metadata before rendering; it never renders the
email/password form when health identifies a Cloud-managed instance. A missing
instance session returns through Cloud's /v1/stacks/:slug/entry-redirect.
Cloud renews the tenant session from the existing Cloud session, or sends the
user through its sign-in flow. The original tenant path, query, and fragment
travel as returnTo so the user returns to the same task.
Both the Cloud origin and stack slug come from the server's health metadata
(PAPERCLIP_CLOUD_API_ORIGIN and PAPERCLIP_STACK_SLUG). Do not infer the
environment from the browser hostname or hardcode staging/production domains.
Missing configuration shows an unavailable state. An automatic recovery attempt
is limited per browser tab until a session is verified, with a five-minute
expiry and an explicit retry link if recovery fails. Network/server failures
show an error rather than treating the user as signed out.
Self-hosted authenticated instances retain their instance sign-in form, and
local_trusted instances retain their normal access path.
The account create hook keeps local:credential on new email/password accounts
so a surviving Better Auth 1.7.2 process can still sign those users in during an
upgrade. This internal field is not client input. Better Auth 1.7.16 still owns
account lookup and the unique (provider_id, account_id) key. Existing NULL
issuer rows remain readable by the new version. Cloud workspace handoff creates
users and sessions without account rows. No social provider is configured here;
other providers retain their trusted internal issuer, or NULL when absent. This
bridge does not claim old-reader compatibility for those unconfigured providers.
Cloud stack Admins can change experimental settings on their dedicated instance. This permission comes from the current trusted Cloud stack role and does not grant other instance-admin powers. Members, Support users, and agents cannot change experiments. Operator-hidden settings and Cloud-managed feature values remain protected. Staging allows saved overrides for its editable experiments; production retains its managed feature policy.
1. Purpose
Paperclip supports two runtime modes:
local_trustedauthenticated
authenticated supports two exposure policies:
privatepublic
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_trustedvsauthenticated, plusprivate/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
- implicit board access belongs to the operator's own local processes. On Linux and macOS, a request that comes from inside an agent run's process tree receives no implicit board access and must authenticate with the run's own credentials. On Linux, a request whose process the server cannot inspect receives implicit board access only when every same-user process that the server cannot inspect has a readable operator parent chain outside any agent run. Requests over IPv4 and IPv6 loopback are covered. If the platform has no process inspection, or
/proc/net/tcpand/proc/net/tcp6cannot be read, the server keeps the previous behavior and logs a warning. Other platforms keep the previous behavior.
authenticated + private
- login required
- low-friction URL handling (
autobase 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=trueto opt in - bind can be
loopback,lan,tailnet, orcustom
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=falseonly when an explicit front-door limiter covers the deployment - recommended bind is
loopbackbehind a reverse proxy; directlan/customis advanced - local stdio MCP runtime slots fail closed by default; set
PAPERCLIP_TRUSTED_MCP_RUNTIME_HOSTonly 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:
- quickstart
--yesdefaults toserver.bind=loopbackand thereforelocal_trusted/private - advanced server setup asks reachability first:
Trusted local→bind=loopback,local_trusted/privatePrivate network→bind=lan,authenticated/privateTailnet→bind=tailnet,authenticated/privateCustom→ manual mode/exposure/host entry
- raw host entry is only required for the
Custompath - 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
authUsersfor Board identity instance_user_rolesentry for Board admin authoritycompany_membershipsintegration 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-boardadmin role - ensures active owner membership for the claiming user across existing companies
- promotes current signed-in user to
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:
- open the Paperclip URL from the private network or appliance UI
- sign in or create a Paperclip account
- choose
Claim this instanceon 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 authenticateduses Better Auth sessions and bootstrap invite flowlocal_trustedensures a real local Board user principal inauthUserswithinstance_user_rolesadmin access- company creation ensures creator membership in
company_membershipsso user assignment/access flows remain consistent
10. Naming and Compatibility Policy
- canonical naming is
local_trustedandauthenticatedwithprivate/publicexposure - 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 - operator workflows:
doc/DEVELOPING.mdanddoc/CLI.md - invite/join state map:
doc/spec/invite-flow.md