Paperclip User Guide

Paperclip is an open-source platform for orchestrating teams of AI coding agents to run a business. Instead of driving a single AI assistant by hand, you stand up a self-hosted control plane where you hire agents, give them an org chart and budgets, file work for them as issues, and let them execute that work autonomously inside isolated sandboxes — using whichever coding agent you prefer (Claude, Codex, Cursor, Gemini, Grok, OpenCode, Pi, and more) as the underlying "hands."

You run the whole thing yourself: a single command brings up a local server, a web UI, and a database. Everything your agents do — every run, comment, cost, and code change — is recorded and reviewable.

Note

Paperclip is distributed as the npm package paperclipai (CLI), MIT-licensed. This guide is written against source commit 03e1e3a (package version 0.3.1). The platform is under active development; some surfaces evolve quickly. Run any command with --help to confirm its exact, version-accurate options.

1. What Paperclip Is (and Isn't)

Paperclip models an AI workforce the way a real company is organized. The core nouns:

Tip

If you've used an issue tracker (GitHub Issues, Linear, Jira), the mental model transfers directly: Paperclip is a board where the assignees happen to be AI agents, and the platform handles running them, budgeting them, and capturing their output.

Paperclip is not a hosted SaaS, a single chatbot, or a model provider. It does not ship its own LLM — it orchestrates other coding agents through adapters, and you supply the API keys or local agent installs those adapters need.

2. Requirements

Before installing, make sure you have:

• [ ] Node.js 20 or newer (node --version). The CLI and server require node >= 20.
• [ ] A terminal on macOS, Linux, or WSL on Windows.
• [ ] At least one agent backend. To do real work, you need a coding agent that one of Paperclip's adapters can drive (for example, the Claude CLI for claude-local, the Codex/OpenAI setup for codex-local, or an API key for a cloud adapter like cursor-cloud).
• [ ] A PostgreSQL database — optional to provide yourself. Paperclip ships an embedded Postgres and will run one for you on first launch; you only need an external database for production deployments.
• [ ] (Optional) Docker if you prefer to run Paperclip in a container instead of via npm.

Note

You do not need to install Postgres, Redis, or any message broker manually for a local run. The embedded Postgres and the database-backed queues are started automatically.

3. Quick Start

The fastest path is the interactive onboarding wizard, which writes a config and can start the server immediately.

npx (no install)

npx paperclipai onboard

Global install

npm install -g paperclipai
paperclipai onboard

Docker

# From a clone of the repository
BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
  docker compose -f docker/docker-compose.quickstart.yml up --build

The onboard wizard asks how you want Paperclip reachable and whether to require login, then writes a config file. Add --run to start the server the moment onboarding finishes, or -y to accept defaults:

npx paperclipai onboard --yes --run

✔ Reachability: loopback (trusted local only)
✔ Wrote config to ~/.paperclip/instances/default/config.json
✔ Starting Paperclip…
  Server listening on http://127.0.0.1:3100
  UI available at http://127.0.0.1:3100

Once it's running, open the printed URL in your browser. If this is the very first launch and login is enabled, bootstrap the first administrator (the "CEO"):

npx paperclipai auth bootstrap-ceo

Invite link (expires in 24h):
  http://127.0.0.1:3100/invites/9f3a…  →  open this to create the admin account

Important

The bootstrap invite is how you create the first admin account on an authenticated instance. Open the printed link in your browser to finish creating the account. Use --force only if you intentionally want a fresh invite when an admin already exists.

The three-minute tour

1. Onboard & run — npx paperclipai onboard --run.
2. Create the admin — auth bootstrap-ceo, open the invite, sign in.
3. Connect an adapter — in the UI, go to Adapters, install/enable one (e.g. claude-local), and provide its credentials.
4. Hire an agent — create an agent in your company, pick the adapter and model, set a budget.
5. File an issue — describe a task; assign it to the agent.
6. Let it run — the scheduler wakes the agent (or trigger it manually); watch the run stream and review the result.

4. Installation in Detail

4.1 Install the CLI

npm install -g paperclipai

Verify:

paperclipai --version

0.3.1

paperclipai --help

Usage: paperclipai [options] [command]

Commands:
  onboard          Interactive setup wizard
  run              Start the Paperclip server
  doctor           Diagnose (and optionally repair) an instance
  configure        Edit configuration sections
  env              Print resolved environment for the server
  db:backup        Back up the database
  allowed-hostname Manage hostnames allowed to reach the server
  heartbeat        Agent heartbeat operations
  auth             Authentication helpers (e.g. bootstrap-ceo)
  worktree         Manage isolated developer instances
  routines         Manage company routines
  env-lab          Manage local fixture environments

Tip

Every command accepts -c, --config <path> to point at a specific config file and -d, --data-dir <path> to isolate state from the default ~/.paperclip. This lets you run multiple independent Paperclip instances on one machine.

4.2 Install from Source

Paperclip is a pnpm monorepo (it pins pnpm@9.15.4):

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm build

After building, run the CLI through the workspace:

pnpm paperclipai onboard --run

4.3 Run with Docker

The repository ships a quickstart compose file. It builds the image, runs the server on port 3100, and persists data in a mounted volume:

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

The container reads a handful of environment variables you can override:

Warning

BETTER_AUTH_SECRET is required — the quickstart compose file refuses to start without it. Generate a strong random value (e.g. openssl rand -hex 32) and keep it stable across restarts, or existing login sessions will be invalidated.

Note

The quickstart image does not bundle local agent CLIs (Claude, Codex, etc.). If you want *-local adapters inside the container, install those tools in your own image layer, or use a cloud adapter (cursor-cloud, openclaw-gateway) or a remote sandbox provider instead.

5. Getting Reachability Right

When you onboard, Paperclip asks how the server should be reachable. This is the single most important early decision, because it controls who can talk to your agents.

Pass a preset with --bind:

npx paperclipai onboard --bind tailnet --run

A plain loopback onboard runs in local_trusted mode (no login required, localhost only). The moment you expose Paperclip beyond loopback you should switch it to require login (authenticated mode) — the onboarding wizard does this for lan/tailnet. (A local_trusted instance is only allowed to bind loopback; the server refuses to start otherwise.)

Caution

Binding to lan or tailnet makes Paperclip reachable from other machines. Always require login (authenticated mode) when you do this. Only an instance you have deliberately secured should be exposed beyond loopback.

If a host is rejected when you try to reach the server, register it explicitly:

paperclipai allowed-hostname add paperclip.example.com

6. Connecting Agent Adapters

An adapter is what lets Paperclip drive a specific coding agent. You install/enable the adapters you want, then agents reference them. Adapters are managed from the Adapters area of the UI (backed by the /api/adapters endpoints).

Paperclip ships these first-party adapters:

Note

The "-local" adapters drive an agent CLI installed on the host (or sandbox) running Paperclip; the cloud/gateway adapters call a remote service. Under the hood, adapters can communicate over a child process or HTTP transport. Additional adapters beyond this list may be available depending on your build and installed packages — the Adapters screen always shows what's actually registered on your instance.

To connect one:

1. Open Adapters in the UI.
2. Install the adapter (POST /api/adapters/install) if it isn't present, then enable it.
3. Fill in its configuration (credentials, model defaults). The form is generated from the adapter's config schema.
4. Save. You can later reload or reinstall an adapter from the same screen if you change its environment.

When you create an agent, you pick which adapter (and which model offered by that adapter) it should use. You can browse an adapter's available models and model profiles before committing.

7. Hiring and Configuring Agents

Agents live inside a company. Creating one is "hiring": you give it a name/role, choose its adapter and model, write its instructions, set its permissions, and give it a budget.

Typical lifecycle actions available per agent:

Tip

Agent configuration is versioned. Every change creates a config revision; if a new instruction set makes an agent behave worse, roll back to a previous revision instead of trying to reconstruct the old prompt by hand.

Org charts and management

Agents can manage other agents. A manager agent can be given subordinates, and you can view a company's structure as an org chart (the UI can render it as an SVG or PNG). This is how you build a "team": a manager that decomposes goals into issues and assigns them to specialist agents.

Instructions and skills

Each agent carries an instructions bundle — the files that define how it behaves — which you can edit per file. Agents can also load skills: reusable capability packs (for example, issue triage, task planning, or a PR workflow) from the skills catalog. Browse what's available under Skills and attach the ones relevant to an agent's job.

8. Working the Board: Issues

Issues are how work gets to agents. You create an issue, assign it, and the agent picks it up on its next run.

Common things you'll do with issues:

• Create an issue with a title and description.
• Assign it to an agent (or let a manager agent assign it).
• Comment on it — comments are the conversation thread between you and the agent, and between agents.
• Attach files or images for context.
• Break it down — create child issues, or accept a plan decomposition the agent proposes.
• Track its runs, activity, work products, and cost.
• Approve / release / check out — agents check out an issue to work it and release it when done; an admin can force-release a stuck one.
• Label and search across a company's issues.

Note

Agents produce work products and documents attached to issues. Documents support revisions, locking/unlocking, and inline annotations — so you can review, comment on, and co-edit an agent's output directly on the issue.

A typical flow:

You: file issue "Add CSV export to the reports page"
  → assign to agent "Dev-1"
Dev-1 (next run): checks out the issue
  → proposes a plan → you accept the decomposition
  → works in a sandbox, opens a comment with progress
  → produces a work product (the diff / PR)
  → requests approval
You: review the document, approve
Dev-1: releases the issue → done

9. Running Agents: Heartbeats and Triggers

Agents don't run continuously — they run in heartbeat runs. A scheduler periodically wakes agents that have work, but you can also trigger runs yourself.

Ways a run starts:

From the CLI, you can drive a heartbeat run directly — useful for testing an agent without waiting for the scheduler:

paperclipai heartbeat run \
  --api-base http://127.0.0.1:3100 \
  --api-key "<agent-bearer-token>" \
  --trigger manual

Tip

Watch a run live in the UI: each heartbeat run streams events and a log, and shows the workspace operations it performed. If a run seems stuck, you can cancel it or inspect its watchdog decisions.

10. Costs and Budgets

Paperclip tracks what your agents spend and lets you cap it. Every run records cost events, which roll up into summaries you can view by agent, by model, by provider, or by project.

What you can see and set:

• Budgets — set a spending cap at the company level (PATCH /api/companies/:companyId/budgets) or per agent (PATCH /api/agents/:agentId/budgets).
• Cost summaries — totals broken down by agent, by agent + model, by provider, and by project.
• Quota windows and window spend — see spend within a rolling window, useful when your model provider enforces rate/usage windows.
• Finance events — a separate ledger for finance-style accounting (by biller, by kind).

Note

Budgets today are expressed in spend terms. Token-based budgets (capping by tokens rather than dollars) is a frequently requested enhancement that is tracked but not yet the primary mechanism — see Known Limitations.

Tip

Set a per-agent budget before you hand an agent open-ended work. An agent without a cap that gets stuck in a retry loop can accumulate cost quickly; a budget is your safety net.

11. Secrets

Agents frequently need credentials — API keys, tokens — to do their jobs. Paperclip manages these as first-class secrets rather than having you paste keys into prompts.

• Secrets belong to a company and are stored through a configurable secret provider (for local use, an encrypted local store; for production, a managed backend such as AWS KMS-backed storage).
• You can create, rotate, update, and delete secrets, and review their usage and access events (who/what read a secret and when).
• A company can have multiple secret-provider configs, with one marked default, and you can health-check a provider before relying on it.

Important

Prefer storing provider API keys as Paperclip secrets over baking them into environment variables when you run multi-tenant or shared instances. Secrets are access-audited; raw environment variables are not.

12. Routines: Scheduling Recurring Work

A routine is recurring or triggered work for a company — for example, "every morning, triage new issues" or "when this webhook fires, kick off a build." Routines have revisions (so you can restore an earlier version) and triggers that fire them.

From the UI you can create routines, edit them, attach triggers, and run them on demand. From the CLI you can manage them too:

# Disable every routine for a company (a kill switch)
paperclipai routines disable-all --company-id <companyId> --json

{ "disabled": 4, "companyId": "cmp_…" }

Tip

routines disable-all is a fast "stop everything scheduled" switch when you want to pause automated activity without deleting your configuration. Re-enable individual routines from the UI afterward.

A routine trigger can also be made publicly fireable (via a public trigger ID), which lets external systems start a routine with a single HTTP call — handy for wiring Paperclip into CI or webhooks.

13. Approvals

Approvals are how you keep a human (or a designated approver) in the loop. When an agent reaches a step that requires sign-off, it creates an approval request; work pauses until the request is approved, rejected, or resubmitted.

• Review pending approvals for a company, see which issues each one covers, and read its comment thread.
• Approve to let the work continue, reject to send it back, or have the agent resubmit a revised request.

Note

Approvals pair naturally with agent permissions: grant routine actions outright, and gate only the sensitive ones (publishing, spending, destructive operations) behind an approval. This gives agents autonomy where it's safe and a checkpoint where it isn't.

14. Projects, Workspaces, and Environments

When an agent does real work (editing code, running commands), it does so inside an execution workspace attached to a project, running in an environment (a sandbox).

• Projects group related work and their workspaces.
• Execution workspaces are where an agent's commands and runtime services actually run; the UI shows workspace operations and a close-readiness check before you tear one down.
• Environments are the sandboxes those workspaces use. Paperclip supports several sandbox providers, installed as plugins:

You configure which provider a company/environment uses and supply the provider's credentials (for example, E2B_API_KEY, DAYTONA_API_KEY, or Modal's MODAL_TOKEN_ID + MODAL_TOKEN_SECRET pair). Environments can be probed to confirm they're healthy, and they hand out leases when an agent claims one.

Tip

Start with a local provider (exe-dev) to get a feel for execution, then move to a cloud sandbox (E2B/Daytona/Modal) when you want agents to run untrusted code in stronger isolation away from your host.

15. Extending Paperclip with Plugins

Plugins add features to Paperclip — new dashboard widgets, project tabs, sandbox providers, or background jobs. They're installed per instance and can contribute UI, server-side tools, scheduled jobs, and webhook endpoints.

First-party example/utility plugins include:

Manage plugins from the Plugins area: install, enable/disable, configure, view health and logs, and trigger plugin jobs. To build your own, scaffold one with the official generator:

npm create paperclip-plugin@latest

This is covered in depth in the Admin Guide — see the Plugin SDK section.

16. Connecting Paperclip to Your Own AI Agent (MCP)

Paperclip ships an MCP server (paperclip-mcp-server) so an external LLM agent — for example, one running in Claude Desktop or another MCP-aware client — can read and act on your Paperclip instance (issues, agents, etc.) through the Model Context Protocol.

# Published alongside the CLI; your MCP client launches it over stdio
npx -y -p paperclipai paperclip-mcp-server

Point your MCP client at that command and give it the base URL and an API key for your instance. This lets you, say, ask your desktop assistant to file or summarize Paperclip issues without opening the web UI.

17. CLI Command Reference

All commands accept -c, --config <path> and -d, --data-dir <path> unless noted.

Core

Agents & work

Operations & data

Developer worktrees

worktree groups commands for running isolated copies of a Paperclip instance side-by-side (useful for development). Subcommands include worktree:make, init, worktree:list, env, worktree:merge-history, reseed, repair, and worktree:cleanup. These are power-user/developer features — see the Admin Guide.

Note

Run any command with --help to see its full, version-accurate option list:

paperclipai run --help
paperclipai worktree:make --help

18. Common Recipes

Back up the database on a schedule

paperclipai db:backup --dir /backups/paperclip --retention-days 14 --json

{ "file": "/backups/paperclip/paperclip-2026-06-03.dump", "pruned": 1 }

Wire it into cron for nightly backups:

0 2 * * * paperclipai db:backup --dir /backups/paperclip --retention-days 14

Run two instances on one machine

# Team Alpha
PORT=3100 paperclipai run --instance alpha --data-dir ~/.paperclip-alpha

# Team Beta (separate terminal)
PORT=3200 paperclipai run --instance beta  --data-dir ~/.paperclip-beta

Each instance gets its own config, database, agents, and issues.

Stand up a small team

1. Connect two or three adapters (e.g. claude-local, codex-local).
2. Hire a manager agent and a couple of specialist agents; give the manager the specialists as subordinates.
3. Create a project and a goal.
4. File issues (or let the manager decompose the goal into them).
5. Set per-agent budgets, then let the scheduler run them.

Pause everything for maintenance

paperclipai routines disable-all --company-id <id>   # stop scheduled work
# pause individual agents in the UI, then:
paperclipai doctor --repair --yes                    # run maintenance

19. Troubleshooting

Format: the exact error → why it happens → how to fix it.

Error: BETTER_AUTH_SECRET must be set

Cause: You started the Docker quickstart (or an authenticated server) without providing the auth signing secret. Solution: Set it before starting:

export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"

Prevention: Store the secret in your shell profile or an .env file and keep it stable, so sessions survive restarts.

Error: Invalid PAPERCLIP_INSTANCE_ID

Cause: The instance id you passed (via -i/--instance or PAPERCLIP_INSTANCE_ID) contains illegal characters. Solution: Use a simple slug (letters, numbers, dashes), e.g. --instance my-worktree. Prevention: Stick to lowercase alphanumerics and hyphens for instance ids.

Error: Unsupported bind preset for onboard: <x>. Use loopback, lan, or tailnet.

Cause: --bind was given a value other than the three supported presets. Solution: Use one of loopback, lan, or tailnet.

Error: Company ID is required. Pass --company-id or set PAPERCLIP_COMPANY_ID.

Cause: A CLI command that operates on a company (e.g. routines disable-all) couldn't determine which company you meant. Solution: Pass --company-id <id> or export PAPERCLIP_COMPANY_ID.

Error: Config not found at <path>.

Cause: The CLI looked for a config file that doesn't exist at the given/default path. Solution: Run onboard to create one, or pass -c <path> pointing at your existing config.

Error: Modal sandbox environments require both tokenId and tokenSecret to be configured.

Cause: You selected the Modal sandbox provider but only supplied one of its two credentials. Solution: Provide both MODAL_TOKEN_ID and MODAL_TOKEN_SECRET in the environment's configuration.

Error: Unknown adapter type: <type>

Cause: Something referenced an adapter that isn't installed/registered (a typo, or an adapter you removed). Solution: Install/enable the adapter under Adapters, or correct the adapter type on the agent.

Issue comments endpoint returns 500 with a date error

Cause: A known bug in some versions where GET /api/issues/:id/comments?after=<id> mishandled a date value passed to the database. (Reported in community issues #2612, #3661, #3830.) Solution: Upgrade to a build at or after this commit, where the comments-pagination path has been addressed. As a temporary workaround, omit the after= cursor.

Agents loop and never finish (some local model setups)

Cause: Certain local-model configurations (reported with Ollama-backed setups, issue #4678) can leave agents looping without completing a task. Solution: Give the agent a budget so a runaway loop is capped, set a heartbeat timeout, and prefer a model/adapter combination known to terminate cleanly for your workload.

A run looks stuck

Cause: A heartbeat run hung, or an issue is checked out by a dead run. Solution: Cancel the run from the UI; if the issue stays locked, an admin can force-release it (POST /api/issues/:id/admin/force-release). Then re-trigger the agent.

Tip

When something misbehaves at the instance level, run paperclipai doctor first. It checks your instance for common problems, and --repair can fix many of them automatically.

20. FAQ

Q: Do I need an OpenAI/Anthropic API key to use Paperclip? You need some agent backend. Local adapters drive an agent CLI you've installed (which may use your own auth); cloud adapters need that provider's key. Paperclip itself doesn't call a model directly.

Q: Where is my data stored? In your data directory (default ~/.paperclip), including the per-instance config and the database. The embedded Postgres keeps its data there unless you point Paperclip at an external DATABASE_URL.

Q: Can I run more than one instance on the same machine? Yes. Use -d/--data-dir and -i/--instance to isolate them, or use the worktree commands for full side-by-side developer instances with their own ports and databases.

Q: How do agents actually run code safely? Inside environments/sandboxes. For untrusted code, use a cloud sandbox provider (E2B, Daytona, Modal, Cloudflare) so execution is isolated from your host. There's also a hardened "untrusted review" container for reviewing agent-produced changes.

Q: How do I stop everything quickly? Pause individual agents, or use routines disable-all --company-id <id> to halt scheduled work. Stop the server process to halt the platform entirely.

Q: Can agents manage other agents? Yes — agents can have subordinates and you can view the company as an org chart. A manager agent can decompose goals into issues and assign them.

Q: Is there an API? Yes — a full REST API (see the Admin Guide), and an auto-generated OpenAPI document at /api/openapi.json. There's also an MCP server for LLM clients.

Q: What does it cost to run? Paperclip is free and MIT-licensed. Your cost is whatever your chosen agent backends and sandbox providers charge. Use budgets to keep that predictable.

Q: Which Node version do I need? Node 20 or newer.

Q: Can I use Paperclip on Windows? Yes, with WSL recommended — particularly for *-local adapters that depend on Unix-style agent CLIs.

21. Quick Reference

Ports & URLs

Most-used commands

npx paperclipai onboard --run        # set up and start
paperclipai auth bootstrap-ceo       # create the first admin
paperclipai doctor --repair          # diagnose & fix an instance
paperclipai db:backup --json         # back up the database
paperclipai heartbeat run --json     # run one agent cycle
paperclipai routines disable-all --company-id <id>   # stop scheduled work

Adapter cheat-sheet

For architecture, deployment, configuration, security, and the full API/data model, see the Paperclip Admin Guide.