# 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: | Concept | What it is | |---------|-----------| | **Company** | The top-level tenant. All agents, issues, projects, secrets, and budgets belong to a company. One Paperclip instance can host several. | | **Agent** | A configured AI worker you "hire" into a company. It has a role, instructions, permissions, a budget, and a backing **adapter**. Agents can manage other agents (an org chart). | | **Issue** | The unit of work — like a ticket on a board. You (or a manager agent) file an issue; an agent checks it out, works it, comments, and produces results. Issues can have children and decomposed plans. | | **Run** (heartbeat run) | One execution cycle of an agent working on its assigned issues. Runs are triggered on a schedule, by a ping, by a callback, or manually. | | **Adapter** | The pluggable backend that actually drives a coding agent (e.g. `claude-local`, `codex-local`, `cursor-cloud`). Adapters are interchangeable. | | **Environment / Sandbox** | The isolated place an agent's work runs — a local process, or a remote sandbox (E2B, Daytona, Modal, Cloudflare). | | **Routine** | Recurring or triggered work — a way to schedule agent tasks (think cron for agents). | | **Approval** | A gate where a human (or authorized agent) must sign off before work proceeds. | | **Skill** | A reusable capability/instruction bundle agents can load to perform a class of task. | > [!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)" ```bash npx paperclipai onboard ``` === "Global install" ```bash npm install -g paperclipai paperclipai onboard ``` === "Docker" ```bash # 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: ```bash npx paperclipai onboard --yes --run ``` ```text ✔ 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"): ```bash npx paperclipai auth bootstrap-ceo ``` ```text 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 ```bash npm install -g paperclipai ``` Verify: ```bash paperclipai --version ``` ```text 0.3.1 ``` ```bash paperclipai --help ``` ```text 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 ` to point at a specific config file and `-d, --data-dir ` 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`): ```bash git clone https://github.com/paperclipai/paperclip.git cd paperclip pnpm install pnpm build ``` After building, run the CLI through the workspace: ```bash 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: ```bash 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: | Variable | Default | Purpose | |----------|---------|---------| | `PAPERCLIP_PORT` | `3100` | Host port mapping | | `PAPERCLIP_PUBLIC_URL` | `http://localhost:3100` | Public base URL used in links | | `PAPERCLIP_DATA_DIR` | `../data/docker-paperclip` | Host directory for persistent data | | `BETTER_AUTH_SECRET` | *(required)* | Secret that signs auth sessions | | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | *(empty)* | Passed to adapters that need them | > [!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`: | Preset | Reachable from | Use when | |--------|----------------|----------| | `loopback` | This machine only (`127.0.0.1`) | Solo local use — the safe default | | `lan` | Other machines on your local network | You want teammates on the same network to use the UI | | `tailnet` | Devices on your Tailscale tailnet | Private remote access without exposing a public port | ```bash 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: ```bash 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: | Adapter (`type`) | Drives | Notes | |------------------|--------|-------| | `claude-local` | Claude (local CLI) | Local Claude agent; ships a quota probe | | `codex-local` | OpenAI Codex (local) | Local Codex agent; reads `OPENAI_API_KEY` | | `cursor-local` | Cursor (local) | Local Cursor agent | | `cursor-cloud` | Cursor (cloud) | Uses the Cursor SDK / cloud API | | `gemini-local` | Google Gemini (local) | Local Gemini agent | | `grok-local` | xAI Grok (local) | Local Grok agent | | `opencode-local` | OpenCode (local) | Local OpenCode agent | | `pi-local` | Pi (local) | Local Pi agent | | `acpx-local` | Agent Client Protocol agents | Bridges ACP-compatible agents (Claude/Codex via ACP) | | `openclaw-gateway` | Remote agents over a gateway | WebSocket gateway to externally-hosted agents | > [!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: | Action | Effect | |--------|--------| | **Hire / create** | Add the agent to the company | | **Configure** | Edit its instructions bundle, model, and settings (revisions are kept, and you can roll back) | | **Set permissions** | Control what the agent is allowed to do | | **Set budget** | Cap how much the agent may spend (see [Costs & Budgets](#10-costs-and-budgets)) | | **Pause / Resume** | Temporarily stop the agent from being scheduled, then re-enable it | | **Approve** | Grant an agent that's waiting on approval permission to proceed | | **Wake up** | Trigger the agent to run now (`POST /api/agents/:id/wakeup`) | | **Terminate** | Stop the agent's current work | | **Delete** | Remove the 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: ```text 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: | Trigger | How | |---------|-----| | **Scheduled** | The heartbeat scheduler wakes agents on an interval | | **Manual (UI/API)** | Wake a specific agent: `POST /api/agents/:id/wakeup` | | **Manual (CLI)** | Run a heartbeat cycle from the terminal | | **Ping / callback / system** | A run can be triggered by an external ping or a callback from work the agent dispatched | From the CLI, you can drive a heartbeat run directly — useful for testing an agent without waiting for the scheduler: ```bash paperclipai heartbeat run \ --api-base http://127.0.0.1:3100 \ --api-key "" \ --trigger manual ``` | Option | Meaning | |--------|---------| | `--api-base ` | Base URL of the Paperclip server API | | `--api-key ` | Bearer token for the agent making the call | | `--trigger ` | `manual`, `ping`, `callback`, or `system` | | `--timeout-ms ` | Give up after this long | | `--profile ` / `--context ` | Use a saved CLI context profile / file | | `--json` | Machine-readable output | | `--debug` | Show raw adapter stdout/stderr chunks | > [!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](#16-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: ```bash # Disable every routine for a company (a kill switch) paperclipai routines disable-all --company-id --json ``` ```text { "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: | Sandbox provider | Backend | |------------------|---------| | **E2B** | E2B cloud sandboxes | | **Daytona** | Daytona dev environments | | **Modal** | Modal sandboxes | | **Cloudflare** | Cloudflare sandbox (via a deployed bridge worker) | | **exe-dev** | Local executable/dev sandbox | | **fake-sandbox** | Deterministic fake provider (for testing) | 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: | Plugin | What it adds | |--------|--------------| | **plugin-workspace-diff** | A "Changes" tab showing the diff of a workspace | | **plugin-llm-wiki** | A local-file knowledge wiki: ingest sources, browse, query, lint, and maintain | | **plugin-file-browser-example** | A project file browser with an in-UI editor | | **plugin-hello-world-example** | A minimal dashboard widget (reference) | | **plugin-kitchen-sink-example** | Demonstrates the full plugin surface in one package | 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: ```bash 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. ```bash # 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 ` and `-d, --data-dir ` unless noted. ### Core | Command | Purpose | |---------|---------| | `onboard [--bind ] [-y] [--run]` | Interactive setup; optionally start immediately. `--bind` = `loopback`/`lan`/`tailnet` | | `run [-i ] [--bind ] [--repair / --no-repair]` | Start the server for an instance (default instance `default`) | | `doctor [--repair] [-y]` | Diagnose the instance; `--repair` attempts automatic fixes | | `configure [-s
]` | Edit a config section: `llm`, `database`, `logging`, `server`, `storage`, `secrets` | | `env` | Print the resolved server environment | | `allowed-hostname …` | Manage hostnames allowed to reach the server | ### Agents & work | Command | Purpose | |---------|---------| | `heartbeat run [--api-base ] [--api-key ] [--trigger ] [--timeout-ms ] [--json] [--debug]` | Drive one agent heartbeat cycle | | `auth bootstrap-ceo [--force] [--expires-hours ] [--base-url ]` | Create the first-admin invite | | `routines disable-all [--company-id ] [--json]` | Disable all routines for a company | ### Operations & data | Command | Purpose | |---------|---------| | `db:backup [--dir ] [--retention-days ] [--filename-prefix

] [--json]` | Back up the database, with optional pruning | | `env-lab up / status / down / doctor [-i ] [--json]` | Manage local fixture environments for testing | ### 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: > ```bash > paperclipai run --help > paperclipai worktree:make --help > ``` --- ## 18. Common Recipes ### Back up the database on a schedule ```bash paperclipai db:backup --dir /backups/paperclip --retention-days 14 --json ``` ```text { "file": "/backups/paperclip/paperclip-2026-06-03.dump", "pruned": 1 } ``` Wire it into cron for nightly backups: ```bash 0 2 * * * paperclipai db:backup --dir /backups/paperclip --retention-days 14 ``` ### Run two instances on one machine ```bash # 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 ```bash paperclipai routines disable-all --company-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: ```bash 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: . 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 ` or export `PAPERCLIP_COMPANY_ID`. ### Error: `Config not found at .` **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 ` 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: ` **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=` 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 ` 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 | Item | Default | |------|---------| | Server / UI port | `3100` | | Health check | `GET /api/health` | | OpenAPI document | `GET /api/openapi.json` | | Data directory | `~/.paperclip` | ### Most-used commands ```bash 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 # stop scheduled work ``` ### Adapter cheat-sheet | Want to drive… | Use adapter | |----------------|-------------| | Claude (local) | `claude-local` | | Codex / OpenAI (local) | `codex-local` | | Cursor (local / cloud) | `cursor-local` / `cursor-cloud` | | Gemini (local) | `gemini-local` | | Grok (local) | `grok-local` | | OpenCode (local) | `opencode-local` | | Pi (local) | `pi-local` | | ACP-compatible agent | `acpx-local` | | Remote agent over gateway | `openclaw-gateway` | For architecture, deployment, configuration, security, and the full API/data model, see the **Paperclip Admin Guide**. --- _Generated June 2026 from paperclipai/paperclip at 03e1e3a. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._