Paperclip Administrator & Developer Guide

This guide is the operational and architectural reference for Paperclip — a self-hosted platform that orchestrates teams of AI coding agents to do work autonomously. It covers the system architecture, every configurable subsystem, deployment topologies, security posture, the data model, the API surface, and the internals a developer would need to extend or operate the platform.

It is written against source commit 03e1e3a (package version 0.3.1, MIT). For end-user/operator tasks (hiring agents, filing issues, running the CLI day-to-day), see the Paperclip User Guide; this document assumes that material and goes deeper.

1. Executive Summary

Paperclip is a single-deployment control plane for an AI workforce. Operators stand up one server that hosts:

• a REST API (Express) with ~300+ endpoints and an auto-generated OpenAPI document,
• a React/Vite single-page UI served from the same process,
• a paperclipai CLI for setup, operations, and developer worktrees,
• an embedded PostgreSQL (or an external one) accessed through Drizzle ORM,
• a plugin runtime (sandboxed JSON-RPC workers) and a plugin SDK,
• an MCP server so external LLM clients can drive the instance, and
• a fleet of interchangeable agent adapters and sandbox providers.

The mental model is a company: companies contain agents (backed by adapters) that work issues in environments/sandboxes, governed by budgets, approvals, routines, secrets, and an org chart.

2. Architecture

2.1 Component diagram

                          ┌───────────────────────────────────────────────┐
   Browser ──HTTP/WS────► │                Paperclip Server                │
   (React SPA, Vite)      │                  (Express)                     │
                          │                                                │
   CLI ──────HTTP───────► │   middleware/ ─► routes/ ─► services/          │
   (paperclipai)          │     (auth,        (40 files)   (117 files:     │
                          │      logging,                    agents,        │
   MCP client ─stdio────► │      redaction)                  issues,        │
   (paperclip-mcp-server) │                                  runs,          │
                          │                                  plugins,       │
                          │                                  costs, …)      │
                          │        │              │              │          │
                          │   Drizzle ORM     storage (local/S3)  secrets   │
                          │        │                                        │
                          └────────┼────────────────────────────────────────┘
                                   ▼
                            PostgreSQL (embedded or external; 86 schema files)

   Agent execution (dispatched by services through adapters):
   ┌───────────────────────────── adapters/ ─────────────────────────────┐
   │ claude-local · codex-local · cursor-local · cursor-cloud ·           │
   │ gemini-local · grok-local · opencode-local · pi-local ·              │
   │ acpx-local · openclaw-gateway        (each: index/server/ui/cli)     │
   └──────────────────────────────────────────────────────────────────────┘

   Execution surface (sandbox provider plugins + bridge):
   ┌──────────────── sandbox-providers/ ────────────────┐
   │ e2b · daytona · modal · cloudflare · exe-dev ·      │
   │ fake-sandbox      ⇄  sandbox-callback bridge        │
   └─────────────────────────────────────────────────────┘

2.2 Monorepo layout

All workspace packages publish under the @paperclipai/* scope; the CLI publishes as paperclipai. Internal dependencies use workspace:* so the CLI bundles the adapters, db, server, and shared packages it needs.

2.3 Request lifecycle

1. A request reaches Express; middleware runs first — request logging, log redaction (server/src/log-redaction.ts scrubs user/host identifiers), and authentication (middleware/auth.ts).
2. Auth resolves the actor — a board (human) user, an agent, or anonymous — from a session cookie, an API key, an agent JWT, or a cloud-tenant token.
3. The matched route (server/src/routes/*) validates input with Zod and delegates to one or more services (server/src/services/*).
4. Services read/write PostgreSQL via Drizzle, persist files via the storage layer, and resolve credentials via the secrets manager.
5. Agent work is dispatched through the relevant adapter, which runs the underlying coding agent — locally or inside a sandbox via a provider plugin, mediated by the callback bridge.
6. Plugins receive events and expose tools over the JSON-RPC plugin bridge.

2.4 The adapter contract

Every adapter package exports four entry points so the same adapter can plug into each layer of the stack:

Adapters are registered in a server-side registry (server/src/adapters/registry.ts) and managed at runtime through /api/adapters — install, enable, reload, reinstall, and fetch a config schema. Unknown adapter references raise Unknown adapter type: <type>. Adapters can communicate over a child-process or HTTP transport (server/src/adapters/process, server/src/adapters/http).

Note

Adapters are hot-manageable: POST /adapters/:type/reload re-reads configuration and POST /adapters/:type/reinstall performs a full teardown/re-init, both without restarting the server.

3. System Requirements

Provider credentials

Agents and sandboxes need third-party credentials, supplied as environment variables or Paperclip secrets:

4. Deployment Topologies

Paperclip is a single-server application; there is no built-in horizontal scaling (the embedded Postgres and bridge queue assume one process owns the state). Scale vertically and offload the database/storage for heavier loads.

4.1 Reachability and deployment posture

Two orthogonal axes control exposure. The default for a fresh instance is local_trusted + private.

The server enforces the safe combinations at startup: local_trusted requires loopback host binding and private exposure; authenticated + public requires an explicit public base URL. Anything reachable off-host should therefore run authenticated.

Caution

Never run local_trusted mode off loopback — it performs no authentication, and the server will refuse to start (local_trusted mode requires loopback host binding). The onboarding wizard switches to authenticated automatically for lan/tailnet binds; preserve that when scripting deployments.

4.2 Local / single user

npx paperclipai onboard --yes --run        # local_trusted + loopback, embedded Postgres

Zero external dependencies — the embedded Postgres and local storage are provisioned automatically under ~/.paperclip.

4.3 Docker (quickstart)

docker/docker-compose.quickstart.yml builds the image and runs the server on port 3100 with a bind-mounted data volume:

BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
  docker compose -f docker/docker-compose.quickstart.yml up --build

Key container environment (from the compose file):

4.4 AWS ECS Fargate

docker/ecs-task-definition.json is a ready template for a public, authenticated deployment:

• Fargate task: 2 vCPU / 4 GB, container port 3100.
• Environment: NODE_ENV=production, SERVE_UI=true, PAPERCLIP_DEPLOYMENT_MODE=authenticated, PAPERCLIP_DEPLOYMENT_EXPOSURE=public, PAPERCLIP_MIGRATION_AUTO_APPLY=true, HEARTBEAT_SCHEDULER_ENABLED=true.
• Secrets pulled from AWS Secrets Manager: DATABASE_URL, BETTER_AUTH_SECRET, ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN.
• Persistent data on EFS (encrypted in transit) mounted at /paperclip.
• Health check: curl -f http://localhost:3100/api/health.
• Logs to CloudWatch (/ecs/paperclip).

Important

For public deployments, point PAPERCLIP_PUBLIC_URL (and, if you fix the auth base URL explicitly, PAPERCLIP_AUTH_PUBLIC_BASE_URL with PAPERCLIP_AUTH_BASE_URL_MODE=explicit) at the externally reachable URL, and set BETTER_AUTH_TRUSTED_ORIGINS for any additional front-end origins.

4.5 Podman / systemd (Quadlet)

docker/quadlet/ provides Quadlet unit files for running the container as a systemd-managed service (Podman). Use this for rootless, auto-restarting host deployments without a full container orchestrator.

4.6 Untrusted review sandbox

docker/docker-compose.untrusted-review.yml + docker/untrusted-review/Dockerfile run a hardened container for reviewing agent-produced changes: cap_drop: ALL, no-new-privileges, a size-limited tmpfs for /tmp, and isolated volumes. Use it when you want to inspect or execute agent output away from any trusted context.

4.7 External PostgreSQL

export DATABASE_URL="postgresql://user:pass@db-host:5432/paperclip"
export PAPERCLIP_MIGRATION_AUTO_APPLY=true
paperclipai run

Provide DATABASE_MIGRATION_URL separately if migrations need a more privileged connection than the runtime user. Embedded Postgres data does not auto-migrate to an external database — dump and restore it deliberately.

4.8 Reverse proxy

Terminate TLS at nginx/Traefik/Caddy and proxy to the server port (3100), forwarding Upgrade/Connection headers for WebSocket and using long read timeouts (agent runs are long-lived). Set PAPERCLIP_PUBLIC_URL and BETTER_AUTH_TRUSTED_ORIGINS to the external origin.

4.9 Startup validation errors

The server validates the deployment configuration on boot and exits with a precise message if it is unsafe or incomplete:

Tip

Run paperclipai doctor (with --repair) to surface and fix most of these before they block a start; paperclipai env prints the fully resolved deployment configuration so you can verify mode/exposure/host/port up front.

5. Configuration Reference

Configuration comes from environment variables plus a per-instance JSON config (PAPERCLIP_CONFIG, default under ~/.paperclip/instances/<id>/config.json). The onboard wizard writes the config; paperclipai configure -s <section> edits sections (llm, database, logging, server, storage, secrets); paperclipai env prints the resolved environment. Environment variables override the file; the file overrides built-in defaults.

The tables below catalog the environment variables Paperclip reads, grouped by subsystem. Defaults are shown only where confirmed in source; where a default is environment-derived or set during onboarding, it is left blank — run paperclipai env to see the resolved value for your instance.

5.1 Core & server

5.2 Authentication & authorization

5.3 Agent identity (JWT)

5.4 Database & backups

5.5 Storage

5.6 Secrets

5.7 Scheduler, bridge, runtime & limits

6. Authentication & Authorization

6.1 Actor model

The auth middleware resolves a request to one of three actor kinds — board (human user), agent, or anonymous — from whichever credential is present:

6.2 Bootstrapping the first admin

On an authenticated instance, the first administrator (the "CEO") is created from a one-time invite:

paperclipai auth bootstrap-ceo --expires-hours 48

This prints an invite link (claimed via the /bootstrap/claim and /invites/:token flows). --force issues a new invite even if an admin already exists. The CLI reads DATABASE_URL, PAPERCLIP_PUBLIC_URL/PAPERCLIP_AUTH_PUBLIC_BASE_URL, and the better-auth URLs to build the link.

Note

In local_trusted mode this is unnecessary — the CLI notes that the bootstrap invite is only required for authenticated mode (loopback users are implicitly the board).

6.3 Invites, board-claim & CLI auth

• Invites — companies issue invite tokens (/invites/:token, with onboarding text, logo, and skills index served per-invite); admins revoke them.
• Board-claim — a token-based flow (/board-claim/:token) to claim board access.
• CLI auth — challenge/response (/cli-auth/challenges/:id, /cli-auth/me, /cli-auth/revoke-current) lets the CLI obtain a session without a browser-stored cookie.
• Join requests & members — companies expose membership, join-requests, and a user directory.

6.4 Agent credentials

Agents authenticate with per-agent API keys or short-lived JWTs. Keys are created and revoked via /agents/:id/keys. JWTs are signed with PAPERCLIP_AGENT_JWT_SECRET (HS256) and carry the configured issuer/audience and TTL. The CLI's heartbeat run passes an agent bearer token via --api-key.

Warning

A known issue (#7450) exists where run-stamped writes can 500 when a gateway JWT's run_id has been pruned from heartbeat_runs (the FK lacked ON DELETE SET NULL). If you operate at high run volume, track this in your upgrade notes.

7. Agent Execution Model

7.1 Heartbeat runs

Agents execute in discrete heartbeat runs. A scheduler (HEARTBEAT_SCHEDULER_ENABLED, tick HEARTBEAT_SCHEDULER_INTERVAL_MS, default 30 s) wakes agents that have work; runs are also triggerable manually (POST /agents/:id/wakeup, or POST /agents/:id/heartbeat/invoke) and via the CLI heartbeat run. A run carries a trigger of manual, ping, callback, or system.

Run-related surfaces:

• /companies/:companyId/heartbeat-runs, /companies/:companyId/live-runs, /instance/scheduler-heartbeats — fleet-level views.
• /heartbeat-runs/:runId plus /events, /log, /workspace-operations, /cancel, /watchdog-decisions — per-run inspection and control.
• /issues/:issueId/live-runs, /issues/:issueId/active-run — runs scoped to an issue.

7.2 Watchdog & recovery

Runs are supervised by a watchdog (decisions recorded per run) and a recovery subsystem (server/src/services/recovery/) that handles stalled/dead runs. Issues carry recovery actions (/issues/:id/recovery-actions, /recovery-actions/resolve) and a monitor (/issues/:id/monitor/check-now, /scheduled-retry/retry-now).

Note

Execution locks tie a run to an issue checkout. A frequently requested enhancement (#7458) is a server-side TTL that auto-clears execution locks left behind by dead runs without operator intervention. Until then, an admin can POST /issues/:id/admin/force-release a stuck issue.

7.3 Cross-instance / cloud upstreams

/cloud-upstreams/* provides a flow to connect an instance to an upstream and push runs to it (preview, push, cancel, activate). This underpins syncing work between a local instance and a hosted/cloud Paperclip.

8. Work Model: Issues, Approvals, Goals

8.1 Issues

Issues are the core work unit (server/src/routes/issues.ts — the single largest route module). Beyond basic CRUD and search, the issue surface includes:

• Comments & interactions — threaded discussion (/issues/:id/comments, /interactions), feedback votes and traces.
• Documents & work products — versioned documents with lock/unlock, revisions, and inline annotation threads (/issues/:id/documents/:key/...), plus work products (the deliverables).
• Attachments — uploaded files/images, gated by PAPERCLIP_ALLOWED_ATTACHMENT_TYPES / PAPERCLIP_ATTACHMENT_MAX_BYTES.
• Hierarchy & planning — children (/issues/:id/children) and accepted plan decompositions.
• Lifecycle — checkout/release, admin force-release, read/inbox-archive state, labels, and per-issue approvals.
• Tree control — /issues/:id/tree-control/* and /tree-holds/* coordinate work across an issue tree (holds prevent concurrent conflicting work on related issues).

Important

Several historical 500s on GET /issues/:id/comments?after=<cursor> (community issues #2612, #3661, #3830) stemmed from a Date value being passed where the Postgres driver expected a string in the comment-pagination path. Ensure you run a build where this is fixed; the bug surfaces specifically on the after= cursor.

8.2 Approvals

Approvals (/companies/:companyId/approvals, /approvals/:id/...) gate sensitive work: approve, reject, resubmit, and a comment thread per approval. They bind to issues (/issues/:id/approvals).

8.3 Goals & dashboard

Goals (/companies/:companyId/goals) track company objectives; the dashboard route aggregates company state for the UI overview.

9. Adapter Subsystem

Adapters are the pluggable agent backends. The registry resolves an adapter type to its implementation; agents reference a type and a model.

Adapter management API (server/src/routes/adapters.ts): GET /adapters, POST /adapters/install, GET/PATCH/DELETE /adapters/:type, PATCH /adapters/:type/override, POST /adapters/:type/reload, POST /adapters/:type/reinstall, GET /adapters/:type/config-schema, GET /adapters/:type/ui-parser.js. Model discovery is per-company-per-adapter (/companies/:companyId/adapters/:type/models, /model-profiles, /detect-model). The /llms/agent-configuration*.txt endpoints expose adapter configuration to LLM clients.

Tip

Document and operate adapters as interchangeable backends, not as bespoke integrations. A given agent's behavior is defined by its instructions + skills + model; the adapter is just which engine runs it. This is what lets you A/B different engines on the same work.

10. Environments, Workspaces & Sandbox Providers

10.1 The execution surface

• Projects (/companies/:companyId/projects) own workspaces (/projects/:id/workspaces).
• Execution workspaces (/companies/:companyId/execution-workspaces, /execution-workspaces/:id) are where commands and runtime services actually run; they expose runtime-service/command actions, a close-readiness check, and a workspace-operations log.
• Environments (/companies/:companyId/environments) describe sandbox capabilities, hand out leases (/environments/:id/leases, /environment-leases/:leaseId), and can be probed for health.

10.2 Sandbox providers (plugins)

Sandbox providers are plugins implementing a common provider interface:

10.3 The callback bridge

packages/adapter-utils/src/sandbox-callback-bridge.ts plus the PAPERCLIP_BRIDGE_* settings implement a queue-based bridge so code running inside a sandbox can call back into the Paperclip host (runtime API). The Cloudflare provider additionally ships a Worker bridge-template that proxies between the Cloudflare sandbox and the host. The bridge is the security boundary between untrusted sandboxed execution and the trusted host — protect it with PAPERCLIP_BRIDGE_TOKEN.

Relevant error classes: EnvironmentRunError, PluginSandboxError, CloudflareBridgeError, ExeDevApiError, plus provider SDK errors (SandboxNotFoundError, TimeoutError, CommandExitError).

11. Plugin Runtime & SDK

11.1 Architecture

Plugins extend the platform with UI, tools, jobs, and webhooks. Each plugin declares a manifest, a worker, and (optionally) a UI bundle:

"paperclipPlugin": {
  "manifest": "./dist/manifest.js",
  "worker":   "./dist/worker.js",
  "ui":       "./dist/ui/"
}

The host runs the worker as a sandboxed JSON-RPC process (packages/plugins/sdk/src/protocol.ts), exchanging messages over the plugin bridge. A capability model (host-client-factory.ts) gates what a worker may do: requests beyond a plugin's grant raise CapabilityDeniedError or InvocationScopeDeniedError; malformed RPC raises JsonRpcParseError / JsonRpcCallError.

11.2 What plugins can contribute

11.3 Authoring a plugin

Scaffold with the generator (@paperclipai/create-paperclip-plugin):

npm create paperclip-plugin@latest

A plugin dev server (paperclip-plugin-dev-server) serves the UI during development. First-party reference plugins demonstrate the surface — plugin-kitchen-sink-example intentionally exercises the full API, plugin-hello-world-example is the minimal widget, plugin-orchestration-smoke-example covers orchestration-grade APIs, and plugin-workspace-diff / plugin-llm-wiki / plugin-file-browser-example are production-style features.

Note

Plugins can own database schema and migrations within their own scope (e.g. plugin-llm-wiki ships migrations), keeping plugin tables isolated from core tables.

12. Skills Catalog

packages/skills-catalog/ is a build-time catalog of agent skills, split into bundled (always available — e.g. paperclip-operations/issue-triage, task-planning, software-development/github-pr-workflow, quality/qa-acceptance, docs/doc-maintenance, product/wireframe) and optional (e.g. browser/agent-browser, content/release-announcement, product/design-critique) sets. The catalog builder validates each skill package (it raises ${packageJsonPath} must declare a package version. for malformed entries) and generates an index. Skills are served to agents and clients via /skills/available, /skills/index, /skills/:skillName, and per-company skill endpoints; repo-level skills under skills/ (e.g. paperclip-create-agent, paperclip-create-plugin, terminal-bench-loop) document agent/plugin authoring workflows.

13. Routines & Triggers

Routines (server/src/routes/routines.ts) are scheduled/triggered company workflows with full revision history:

The CLI exposes routines disable-all --company-id <id> as an operational kill switch. A frequently requested feature (#7448) is letting manager agents create and manage routines for their subordinates.

14. Costs, Budgets & Finance

Paperclip records cost and finance events and aggregates them many ways (server/src/routes/costs.ts):

Note

Budgets are spend-based today; token-based agent budgets are an open enhancement (#1756). Quota windows align cost accounting with provider rate/usage windows — useful when a provider meters by rolling window rather than absolute spend.

15. Secrets Management

Secrets are company-scoped and provider-backed (server/src/routes/secrets.ts, server/src/secrets/):

• Providers — local (encrypted file via PAPERCLIP_SECRETS_MASTER_KEY[_FILE]) or AWS KMS-backed (PAPERCLIP_SECRETS_AWS_* plus standard AWS credential resolution). List/configure providers, mark one default, and health-check them (/secret-providers, /secret-provider-configs).
• Secrets — create, update, rotate, delete (/companies/:companyId/secrets, /secrets/:id, /secrets/:id/rotate), with audit surfaces /secrets/:id/usage and /secrets/:id/access-events.
• Strict mode — PAPERCLIP_SECRETS_STRICT_MODE makes any decryption failure fatal, which surfaces key-rotation problems immediately instead of silently degrading.

Caution

The local provider's security reduces to the secrecy of the master key. Protect PAPERCLIP_SECRETS_MASTER_KEY_FILE with strict file permissions and disk encryption, or use the AWS KMS provider so the data-encryption keys never live in plaintext on the host.

16. MCP Server

packages/mcp-server/ publishes the paperclip-mcp-server binary (built on @modelcontextprotocol/sdk + Zod). It lets an external MCP-aware LLM client read and act on a Paperclip instance over stdio. Point your client's command at it and provide the instance base URL and an API key. Server-side, /llms/*.txt endpoints expose agent/adapter configuration in an LLM-friendly form.

17. Data Model & Database

The data layer is Drizzle ORM over PostgreSQL, with 86 schema files in packages/db/src/schema/ and 94 migrations in packages/db/src/migrations/.

17.1 Major entity groups

17.2 Migrations & embedded Postgres

Migrations are generated with drizzle-kit (pnpm --filter @paperclipai/db generate) and applied via pnpm --filter @paperclipai/db migrate or automatically on startup (PAPERCLIP_MIGRATION_AUTO_APPLY). A check:migrations guard enforces migration numbering. Embedded Postgres is a patched embedded-postgres@18.1.0-beta.16 (see patches/); its port is set by PAPERCLIP_EMBEDDED_POSTGRES_PORT.

17.3 Backup & restore

packages/db/src/backup-lib.ts drives backups using pg_dump/psql (paths overridable via PAPERCLIP_PG_DUMP_PATH / PAPERCLIP_PSQL_PATH). The CLI db:backup supports --dir, --retention-days, --filename-prefix, and --json; the API exposes POST /instance/database-backups. Schedule db:backup via cron for unattended backups.

18. API Reference

The server mounts ~328 routes across 40 route modules under the /api prefix, with an auto-generated OpenAPI document at GET /api/openapi.json (built from an OpenAPIRegistry). Treat that document as the authoritative, always-current contract; the table below is the resource map.

Tip

Generate clients from /api/openapi.json rather than hand-coding paths — the route surface is large and evolving, and the OpenAPI document is regenerated from the registry on every build. Many resources are mounted under a company scope (/companies/:companyId/...) while individual records are addressed by their own id (/issues/:id, /agents/:id, /routines/:id).

19. Security

19.1 Posture checklist

• [ ] BETTER_AUTH_SECRET set (256-bit random) for any non-loopback deployment.
• [ ] A distinct PAPERCLIP_AGENT_JWT_SECRET from the auth secret.
• [ ] PAPERCLIP_DEPLOYMENT_MODE=authenticated whenever exposure ≠ loopback.
• [ ] PAPERCLIP_ALLOWED_HOSTNAMES + BETTER_AUTH_TRUSTED_ORIGINS constrained to known hosts/origins.
• [ ] PAPERCLIP_AUTH_DISABLE_SIGN_UP=true once your initial users exist.
• [ ] PAPERCLIP_BRIDGE_TOKEN set so only authorized processes can use the sandbox-callback bridge.
• [ ] Secrets via AWS KMS (PAPERCLIP_SECRETS_PROVIDER=AWS) or a tightly-permissioned master key file; consider PAPERCLIP_SECRETS_STRICT_MODE.
• [ ] Attachment MIME allow-list and size cap configured.
• [ ] Untrusted agent code executed only in cloud sandboxes / the untrusted-review container, never directly on the host.

19.2 Built-in protections

• Log redaction (server/src/log-redaction.ts) scrubs identifiers (USER, LOGNAME, USERNAME, etc.) from logs.
• Hardened review container (docker/untrusted-review/) drops all capabilities and forbids privilege escalation.
• Capability-gated plugins — workers cannot exceed their declared grants (CapabilityDeniedError).
• Hostname allow-listing rejects requests from unexpected hosts; invalid hostnames raise Invalid hostname: <raw>.
• Loopback enforcement — local_trusted mode is rejected on any non-loopback host.
• HTTP error mapping — domain errors extend HttpError (server/src/errors.ts) for consistent status codes.

19.3 Handling a malicious or compromised agent

Agents are privileged actors. Pause or terminate a misbehaving agent immediately (/agents/:id/pause, /terminate), revoke its keys (DELETE /agents/:id/keys/:keyId), force-release any issues it holds, and review its /secrets/:id/access-events to see what it touched. Run untrusted execution only in isolated sandboxes so a compromised run cannot reach the host.

20. Operations Runbook

20.1 Developer worktrees

The worktree command family runs isolated copies of an instance side-by-side — each with its own repo-local config, isolated data dir, server port, and embedded-Postgres port — so developers can work on multiple branches without colliding state:

Warning

reseed and worktree:cleanup are destructive. They guard against operating on a live target DB; --allow-live-target / --force override those guards — use them deliberately. --preserve-live-work keeps copied agent timers and assigned open issues instead of quarantining them.

20.2 env-lab

env-lab up|status|down|doctor manages local fixture environments for testing adapter/sandbox configurations without touching production data.

20.3 Performance tuning

• Database is the first bottleneck. Each heartbeat cycle queries active agents; under many concurrent agents, watch PostgreSQL connection count (SELECT count(*) FROM pg_stat_activity;). Move to an external Postgres with adequate max_connections before scaling agent count.
• Scheduler cadence. Lower HEARTBEAT_SCHEDULER_INTERVAL_MS for snappier response, raise it to reduce database churn.
• Storage I/O. Use S3 storage to remove local disk pressure for attachment-heavy workloads.
• Embedded-Postgres diagnostics. PAPERCLIP_EMBEDDED_POSTGRES_VERBOSE=true logs database activity for slow-query hunting.

21. Build, Test & Release

Releases are scripted (scripts/release.sh with canary/stable channels, GitHub release + rollback helpers) and the npm CLI is bundled via esbuild (scripts/build-npm.sh). The repo enforces guardrails such as check:no-git-push and forbidden-token checks. Test/CI surfaces include Storybook for UI components and a release-smoke Playwright suite that exercises Docker auth/onboarding.

Error class hierarchy (selected)

Error
├── HttpError                  server/src/errors.ts          (HTTP status mapping)
├── EnvironmentRunError        services/environment-run-orchestrator.ts
├── PluginSandboxError         services/plugin-runtime-sandbox.ts
├── CapabilityDeniedError      plugins/sdk/host-client-factory.ts
├── InvocationScopeDeniedError plugins/sdk/host-client-factory.ts
├── JsonRpcParseError /        plugins/sdk/protocol.ts
│   JsonRpcCallError
├── CloudflareBridgeError      sandbox-providers/cloudflare
├── ExeDevApiError             sandbox-providers/exe-dev
├── PaperclipApiError          mcp-server/client.ts
└── ApiError / AuthApiError    ui/src/api

22. Code Quality & Conventions

• Strict TypeScript, ESM throughout. Every package is "type": "module", targets TS 5.7, and publishes typed entry points; the CLI bundles workspace deps via esbuild.
• Zod as the validation spine. packages/shared/src/validators/ (36 files) holds input schemas reused across server, CLI, and UI, and feeds the OpenAPI registry — request validation and API docs share one source of truth.
• Service-oriented server. 117 service files concentrate business logic behind thin route handlers; the recovery/ subdirectory isolates run-recovery concerns.
• Adapter/provider symmetry. Both agent adapters and sandbox providers follow a registry + uniform-interface pattern, which is what makes them swappable.
• Test breadth. Vitest unit/integration (server/src/__tests__ alone has 261 files), Playwright E2E + release-smoke, promptfoo evals, and Storybook stories.

Note

The largest modules — server/src/services (~2.7M chars), server/src/routes (~1.06M chars), ui/src/lib (~0.68M chars), packages/adapter-utils/src (~0.44M chars), and packages/plugins/sdk/src (~0.36M chars) — are the natural focus points for anyone learning the codebase or planning refactors.

23. Known Limitations & Roadmap Signals

Drawn from the issue tracker at this commit:

Scaling beyond a single node is the largest architectural limitation: shared embedded Postgres and the file-backed bridge queue assume one owning process. Production scale means external Postgres + S3 storage + vertical sizing, and (today) one active server.

24. Quick Reference

For user-facing workflows, the adapter/sandbox catalogs, and the CLI day-to-day, see the Paperclip User Guide.