You know what Paperclip solves and how it works under the hood. Now install it. This guide takes you from an empty terminal to a CEO agent running its first heartbeat — 7 steps, 15 minutes.
Every step in this guide offers two paths: the UI (ideal for first-timers) and the CLI (ideal once you’re comfortable or need automation). Pick whichever suits you — the result is the same.
System Requirements — You Need Exactly 3 Things
Before you start, confirm your machine has these:
- Node.js 20 or higher — check with
node --version. If missing or outdated, install via nvm:nvm install 20. - pnpm 9.15 or higher — the monorepo package manager Paperclip uses. Quick install:
npm install -g pnpm. Verify:pnpm --version. - An Anthropic API key — Paperclip needs an LLM adapter for agent execution. This guide uses Claude (Anthropic) as the example. You can also use GPT-4, Gemini, or a locally hosted model — but Claude delivers the most consistent results with Paperclip today.
That’s it. No Docker. No standalone PostgreSQL. No cloud account. Paperclip manages its own embedded database and storage on your machine.
If you already have Node.js and a terminal open — you’re one npm install -g pnpm away from starting.
Install Paperclip — Clone, Install, Run
Two installation paths. Pick the one that fits.
Option 1 — Fastest (one command, no clone needed):
npx paperclipai onboard --yes
This downloads the Paperclip CLI, runs the onboarding wizard with default config (embedded PostgreSQL, port 3100, no authentication), and starts the server automatically. Done.
Option 2 — Clone the repo (recommended if you want to read the source):
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
After pnpm install finishes (1–2 minutes depending on your connection), start the server:
pnpm dev
pnpm dev starts the API server and UI in development mode with watch mode. An embedded PostgreSQL database is created automatically — no separate database setup required.
If you want control over each component — external PostgreSQL instead of embedded, a different port, S3 storage — edit ~/.paperclip/instances/default/config.json directly or re-run pnpm paperclipai onboard. But for a first run, defaults work well.
Paperclip creates ~/.paperclip/instances/default/ with everything it needs:
config.json— server, database, and storage configurationdb/— embedded PostgreSQL data. No separate database install required — Paperclip bundles it.secrets/master.key— encryption key for API credentialslogs/— server logs
When the terminal prints Listening on http://127.0.0.1:3100, the server is ready. Open your browser to http://localhost:3100.
One thing worth noting: all data stays on your machine. No cloud service is called at this stage. The server runs locally, the database runs locally, and the UI is served from the same process. You can run Paperclip completely offline (except when agents need to call LLM APIs).
If port 3100 is already in use, Paperclip will report an error. See the Troubleshooting section at the end.
Onboarding Wizard — Create Your Company, Agent, and First Task via UI
When you open http://localhost:3100 for the first time, Paperclip doesn’t show an empty dashboard. Instead, an Onboarding Wizard appears and walks you through 4 steps to create a company, your first agent, and assign a task immediately. This is the fastest way to get started.
Step 1 — Name your company
The wizard asks you to enter a company name. “My AI Team” or your project name works fine.
A company in Paperclip is a fully isolated workspace. Each company has its own agents, tasks, budgets, and audit trail. Agents in Company A have zero visibility into Company B — like two separate firms sharing an office building.
In practice, many teams map one company to one project: “E-commerce Backend,” “Mobile App,” “Data Pipeline.” Data isolation, budget isolation, access isolation. An agent in Project A can never accidentally read Project B’s code — Paperclip enforces this boundary at the API level.
Step 2 — Create your first agent
The wizard moves to the agent creation screen. Enter a name — “CEO” for example — and select a model (Claude Opus, Claude Sonnet, GPT, etc.). Claude Code and Codex are shown as recommended adapters, with other types collapsed below. The wizard automatically checks the adapter environment — a green animation on success, debug output on failure.
Click Next to continue.
What’s an adapter? In the previous article, we explained that Paperclip is a control plane — it orchestrates, not executes. The adapter is the “muscle”: the runtime where the LLM actually runs. claude_local calls Claude via the Anthropic API on your machine. Paperclip also supports codex_local (OpenAI Codex), cursor (Cursor IDE), gemini_local (Google Gemini, from v0.3.1), openclaw_gateway (OpenClaw), and custom HTTP adapters for any model.
Step 3 — Assign the first task to the CEO
The wizard shows a form to enter the first task. There’s a default placeholder — it asks the CEO to create its own metadata files: AGENTS.md, SOUL.md, HEARTBEAT.md, TOOLS.md. You can use the default or enter a different task.
Step 4 — Publish the issue
Click Publish (or Create Issue) to assign the task to the CEO. The task is created and assigned to the agent.
After publishing, Paperclip automatically triggers a heartbeat for the CEO. The agent wakes up, reads the task, and starts working. You can track progress in the dashboard and inbox.
When the CEO completes its first task, you’ll see a reply in the Inbox — typically the CEO proposing to hire additional agents (e.g., an engineer) and requesting Board approval from you. Click Approve to proceed.
That’s it — 4 steps in the UI, no terminal commands required.
Same Steps via CLI (for Power Users)
If you prefer the terminal over the UI — or need to automate the process — here’s how to do the same steps via CLI.
Create an agent:
pnpm paperclipai agent local-cli ceo --company-id <company-id>
This creates a “ceo” agent with the claude_local adapter. The terminal prints an env vars block — copy and paste it into your terminal:
export PAPERCLIP_API_URL='http://127.0.0.1:3100'
export PAPERCLIP_COMPANY_ID='<your-company-id>'
export PAPERCLIP_AGENT_ID='<your-agent-id>'
export PAPERCLIP_API_KEY='pcp_...'
The local-cli command also installs Paperclip skills into ~/.claude/skills/ — instruction files that teach the agent how to follow the heartbeat protocol, check out tasks, post result comments, and escalate when stuck. Without skills, the agent doesn’t know it belongs to a “company.” With skills, it knows its exact role and the process it must follow.
Create a task:
pnpm paperclipai issue create \
--company-id <company-id> \
--title "Create hello-world.md" \
--description "Create a hello-world.md file with a short project introduction." \
--status todo \
--assignee-agent-id <agent-id>
Trigger a heartbeat manually:
pnpm paperclipai heartbeat run --agent-id <agent-id>
The terminal starts streaming logs in real time. The agent wakes up, calls GET /api/agents/me to confirm identity, GET /api/agents/me/inbox-lite to check for tasks, POST /api/issues/{id}/checkout to claim the task. The whole process takes roughly 30–90 seconds depending on task complexity.
In production, heartbeats run automatically — on an interval or event-driven. Here, you trigger manually to observe the full process.
Configuring Agents After Creation — Customization via UI
Whether you created an agent through the wizard or CLI, you can edit its configuration afterwards in the UI. Navigate to your company, select the agent, and open the settings page. The interface is organized into tabs:
Agent Settings: Change the name (e.g., from “CEO” to a specific name), set a display title for the org chart, describe capabilities (what the agent can do — helps other agents know who to delegate to).
Adapter: Select the adapter type (Claude Code, Codex, Cursor, OpenCode, etc.), configure the working directory (use absolute paths), point to the agent instruction file (path to AGENTS.md).
Config: Choose the model (Claude Opus, Sonnet, or others — you can assign different models to different agents to optimize costs), toggle thinking mode, enable Chrome browser access for the agent.
Heartbeat: Configure the heartbeat interval — how often the agent wakes up, whether automatic heartbeats are enabled or manual trigger only.
You don’t need to change anything for a first run — defaults work well. But when you scale to 5–10 agents, this is where you fine-tune each agent for its role.
See the Results — Dashboard, Audit Trail, and Cost
Back in the UI, open the dashboard. Here’s what you’ll see:
Task status: done — the task completed. Click into it and you’ll find the full comment thread: when the agent checked out, what it did, what it produced.
Cost: each heartbeat records actual cost. Example: “Run #1 — $0.85 — 45s — 1 task completed.” You know exactly where every dollar goes. No surprise invoice at month-end.
Audit trail: every action is tagged with a run ID — the identifier for that heartbeat execution. The agent checked out the task at 14:32:05, posted a comment at 14:32:47, marked done at 14:32:48. Full traceability — who did what, when, at what cost. When you scale to 10 agents, this audit trail is how you maintain control: no agent acts without leaving a trace.
Org Chart: navigate to the Org Chart tab to see a visual hierarchy — who reports to whom, clear structure at a glance. When the CEO hires additional agents (after your approval), the chart updates automatically.
Compare this to the typical way of running AI agents: you open a terminal, launch Claude Code or Cursor, assign work verbally or via prompt, and when it’s done you don’t know how many tokens it consumed, how long it ran, or whether it skipped any steps. Paperclip makes that opaque process fully transparent.
That’s it: 1 company, 1 agent, 1 completed task, a full audit trail, and exact cost figures. All in 15 minutes.
Troubleshooting — 5 Common Issues and Quick Fixes
1. Port 3100 already in use
Error: EADDRINUSE: address already in use :::3100. Fix: kill the existing process (lsof -i :3100 on Mac/Linux, netstat -ano | findstr :3100 on Windows) or change the port in ~/.paperclip/instances/default/config.json under server.port.
2. Node.js version too old
Error: syntax errors or SyntaxError: Unexpected token. Fix: run node --version to check. You need 20+. Quick upgrade: nvm install 20 && nvm use 20.
3. Embedded PostgreSQL won’t start
Error: Failed to start embedded postgres. Common cause: the ~/.paperclip/ directory lacks write permissions, or a previous instance is still running. Fix: pnpm paperclipai doctor --repair — this command diagnoses and fixes most issues automatically.
4. Agent doesn’t pick up the task
The heartbeat runs but the agent reports “No work found.” Check three things: (a) is the task assigned to the correct agent ID? (b) is the task status todo? (c) did you source the environment variables? Verify: echo $PAPERCLIP_AGENT_ID.
5. Heartbeat timeout
The agent starts but times out before completing. Cause: the task is too complex for the default timeout, or the LLM API key is expired or invalid. Fix: increase timeoutSec in agent configuration, or verify your API key on the Anthropic dashboard.
General tip: pnpm paperclipai doctor should be your first step when anything goes wrong. It checks the database, config, permissions, and auto-repairs what it can. Add the --repair flag to auto-apply fixes without confirming each one.
If none of the above resolves your issue — check the logs at ~/.paperclip/instances/default/logs/. The log files capture everything the server does, including errors that may not surface clearly in terminal output.
Next Up: Scaling From 1 Agent to 10
You have 1 working agent, 1 completed task, and all the infrastructure in place. The foundation is solid.
But 1 agent is just the beginning. When you add agent #2, #3, #10 — who reports to whom? Who has approval rights? Who gets budget limits? In the next article, you’ll design an org chart for your AI team — from hierarchy to permissions, from chain of command to budget allocation.
