Files
PaperClipAI/doc/DEPLOYMENT-MODES.md
T
DottaandClaude Opus 5.5 f95bbe081e fix(auth): agent shells can only reach the local API with their own run credentials (#21181)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - In `local_trusted` mode, the server gives board access to local
requests that carry no credentials, so the operator can use the app
without a login
> - Agent runs execute on the same machine, so their tools can also send
local requests
> - An agent run must act only with its own run credentials and
permissions
> - This pull request makes implicit board access belong only to the
operator's own local processes
> - The benefit is that agent shells and tools can only reach the API
with their own run credentials

## Linked Issues or Issue Description

**What happened?**
In `local_trusted` mode, a process inside an agent run could receive the
board identity for an API request that had no credentials. A permission
denial for the agent then did not stop the change.

**Expected behavior**
A request from inside an agent run uses the run's own credentials and
permissions. Implicit board access stays available to the operator's
browser and terminal tools.

**Deployment mode**
`local_trusted` (private, loopback). Authenticated deployments do not
use implicit board access and do not change.

**Additional context**
Found by the chat feature evals. The bundled board skill also described
implicit board access in words that an agent could follow.

## What Changed

- Add `server/src/middleware/local-agent-process-boundary.ts`. For a
request without credentials, it identifies the local process behind the
TCP connection (Linux: `/proc`; macOS: `netstat -anv` and `ps`). If that
process or one of its ancestors belongs to an agent run, the request
gets no implicit board access. An agent run is a descendant of
`paperclip-runnerd`, or a process that carries a run identity variable
(`PAPERCLIP_RUN_ID`, `PAPERCLIP_AGENT_ID`, `PAPERCLIP_AGENT_KEY_ID`,
`PAPERCLIP_RUNNER_INSTANCE_ID`) with a value that is different from the
server's own value.
- The walk stops at the server process and its ancestors. Requests from
the server process itself, and from an operator whose own development
server runs inside the same agent execution, keep board access.
- The result is cached for each connection. Only one process lookup runs
at a time. Connections that arrive during a lookup wait for the next
lookup, which handles all of them together (one `netstat` and two `ps`
calls on macOS, one `/proc` walk on Linux). All lookups are
asynchronous, so they do not block other work in the server.
- `actorMiddleware` and the live events WebSocket upgrade apply the
check in `local_trusted` mode. A refused request is unauthenticated
(`actor.type = "none"`), the same as an anonymous request in
authenticated mode.
- Platforms where the server cannot identify the process (for example
Windows) keep the previous behavior and log one warning.
- Rewrite the `paperclip-board` skill authentication section. It no
longer describes implicit board access to agents, and it says that a 401
or 403 inside an agent run is final.
- Document the behavior in `doc/DEPLOYMENT-MODES.md`.

## Verification

- `cd server && npx vitest run
src/__tests__/local-agent-process-boundary.test.ts`. The test starts a
real `local_trusted` server and real child processes:
- an operator process without credentials gets board access (green
before and after);
  - an in-process request gets board access;
- a process with a run identity gets no board access (red before this
change, green after);
- an agent process that starts a tool with an empty environment gets no
board access (red before, green after);
- an operator inside the same execution as its own server keeps board
access.
- A burst test with a slow inspector: 12 parallel connections and 2
connections that close early. It checks that only one lookup is active
at a time, that the burst needs at most two lookups, that the event loop
stays responsive, and that later requests still work.
- Parser tests for the Linux TCP table and the macOS `netstat` format,
and a test that the runner daemon itself is not treated as an agent
process.
- Ran `agent-auth-middleware`, `agent-identity`, `live-events-ws`,
`live-events-toast`, `live-events-run-read` and
`issue-create-deduplication-routes` tests locally. `npx tsc --noEmit -p
server/tsconfig.json` passes.
- Paid runner E2E evidence for the affected chat cases is linked in a
comment.

## Risks

- Medium. The check runs once for each new local connection without
credentials. On macOS it starts `netstat` and `ps` (about 30 to 80 ms).
On Linux it reads `/proc`. Bearer requests do not run it.
- If a process can not be identified on a supported platform, the
request gets no implicit board access. On Linux, when a same-user
process hides its sockets, the check keeps the previous behavior so that
the operator's browser continues to work.
- This is a boundary for the documented path, not a sandbox. Agent runs
use the operator's OS account. A process that intentionally leaves its
run's process tree, or reads the instance files directly, is outside
this check. The broader option is a product decision: bind implicit
board access to a capability that only the operator's browser and CLI
hold, or run agents under an OS sandbox that blocks the server port.
This pull request does not change `local_trusted` semantics for the
operator.

> 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 and code execution.

## 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
- [ ] All Paperclip CI gates are green
- [ ] 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>
2026-11-12 15:05:15 -06:00

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:

  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
  • 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. Other platforms keep the previous behavior.

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
  • operator workflows: doc/DEVELOPING.md and doc/CLI.md
  • invite/join state map: doc/spec/invite-flow.md