How to Set Up Paperclip: Run a Company of AI Agents From Your Laptop

I run 18 AI agents. Not as a thought experiment. As a daily production setup — on a Mac mini sitting under my desk.

The thing that makes it work isn't the agents themselves. It's the layer above them. The thing that decides who works on what, tracks costs, enforces budgets, and stops an agent from burning £400 on a loop nobody asked for.

That layer is Paperclip.

If you've got even two or three agents, you've already felt the pain: which one is doing what? How much has it spent? Did it finish? Did it go rogue?

This post walks you through setting it up from scratch.

What You're Building

By the end of this, you'll have:

• Paperclip running locally with its own embedded database
• A company with a goal
• A CEO agent that wakes up on a schedule and delegates work
• At least one worker agent that actually does things
• Cost tracking and budget enforcement
• A dashboard where you see everything at a glance

No cloud account required. No Docker required. Just your laptop and Node.js.

Prerequisites

You need two things:

• Node.js 20+
• pnpm 9+

That's it. Paperclip ships with an embedded PostgreSQL — no database setup.

Check you're good:

node --version   # v20+ required
pnpm --version   # 9+ required

If you don't have pnpm:

npm install -g pnpm

Step 1: Install and Onboard

One command:

npx paperclipai onboard --yes

This clones the repo, installs dependencies, and runs an interactive setup wizard. It'll ask you about deployment mode — for local use, pick local_trusted. That gives you localhost-only access with no login required. Fastest path to running.

If you already have the repo cloned:

cd paperclip
pnpm install
pnpm paperclipai run

paperclipai run is the smart path — it auto-onboards if config is missing, runs health checks, and starts the server.

Either way, you end up at http://localhost:3100.

Step 2: Create Your Company

Open the dashboard. Click New Company.

Give it a name and a goal. The goal matters — it's not decoration. Every task your agents work on traces back to this goal. It gives agents context on why they're doing something, not just what.

Bad goal: "Do stuff"

Good goal: "Build the #1 AI-powered note-taking app to $1M MRR in 6 months"

Specific. Measurable. Something an agent can reason about when deciding whether a task is worth doing.

Step 3: Hire Your CEO

Every company needs a CEO. This is the agent at the top of the org chart — it reviews company health, sets strategy, and delegates work down.

Go to the Agents page. Create a new agent:

The adapter config tells Paperclip how to run this agent. claude_local spawns a Claude Code CLI process. codex_local does the same with OpenAI's Codex. Both work locally — no cloud deployment needed.

The CEO's First Heartbeat

When the CEO wakes up, it follows the heartbeat protocol:

1. Check identity (GET /api/agents/me)
2. Review assignments
3. Pick work by priority
4. Checkout the task (atomic — prevents double work)
5. Do the work
6. Update status and comment

On its first heartbeat, the CEO will typically propose a strategic breakdown — how to decompose the company goal into projects and tasks. This gets submitted as an approval request to you (the board).

You're the board. You approve or reject. The CEO proposes, you decide.

Step 4: Build the Org Chart

Once the CEO has a strategy, start adding agents:

CTO — reports to CEO, manages engineering work:

Name: CTO
Role: cto
Reports to: CEO
Adapter: claude_local
Budget: 3000 cents ($30/month)

Engineers — report to CTO, do the actual coding:

Name: Backend Engineer
Role: engineer
Reports to: CTO
Adapter: claude_local
Working directory: ~/projects/my-app
Budget: 2000 cents ($20/month)

The hierarchy matters. It's not just an org chart — it defines:

• Delegation lines — managers create subtasks for their reports
• Escalation paths — stuck agents escalate to their manager
• Budget cascading — spend flows through the tree

Step 5: Set Budgets

This is the part most people skip and then regret.

Set budgets at two levels:

Company Budget

Overall monthly limit for all agents combined.

Per-Agent Budget

Individual cap per agent per month.

Paperclip enforces automatically:

• 80% — soft alert, agent focuses on critical work only
• 100% — hard stop, agent is paused until budget resets

Start conservative. You can always increase. You can't un-spend tokens.

I learned this the hard way. One rogue loop cost me £400 before I had budgets in place. Now every agent has a ceiling. The CEO gets more because strategy work is expensive. Individual engineers get less because their tasks are scoped.

Step 6: Enable Heartbeats

Agents don't run continuously. They wake up on heartbeats — scheduled intervals or event triggers.

Configure heartbeats per agent:

• Schedule — "wake up every 30 minutes"
• On assignment — "wake up when a task is assigned to you"
• On mention — "wake up when someone @-mentions you in a comment"
• Manual — you click "Invoke" in the UI

For a first run, I'd suggest:

• CEO: every 2 hours (strategy doesn't need to happen every 5 minutes)
• Engineers: on assignment + every hour (responsive but not wasteful)

Step 7: Watch It Work

Once heartbeats are enabled, your agents start working. Open the dashboard and you'll see:

• Who's running — which agents are in a heartbeat right now
• What they're doing — current task per agent
• How much they've spent — cost tracking in real time
• Activity log — every status change, comment, and delegation

This is the part that makes it click. You're not managing 18 terminal windows. You're looking at a dashboard that shows you an entire company operating.

The Real Setup: Tailscale + Phone

Here's how I actually run it. Paperclip on the Mac mini, authenticated mode with Tailscale:

pnpm dev --tailscale-auth

This binds to 0.0.0.0 and enables login. I access it from my phone over Tailscale — same Paperclip dashboard, from anywhere. Review tasks on the train. Approve hires from bed. Check costs while making coffee.

For this, change your deployment mode to authenticated/private:

pnpm paperclipai configure --section server

Pick authenticated mode, private exposure, and add your Tailscale hostname to the allowed list:

pnpm paperclipai allowed-hostname your-machine.tailnet.ts.net

Now you've got a company of AI agents accessible from your pocket.

Connecting OpenClaw Agents

If you're already running OpenClaw agents, they plug straight in. In the Paperclip UI:

1. Go to company settings
2. Click Generate OpenClaw Invite Prompt
3. Copy the generated prompt
4. Paste it into your OpenClaw agent's chat

The agent onboards itself — creates its own agent record, configures the adapter, and starts taking work. You just need to approve the join request.

Under the hood, it uses the openclaw_gateway adapter — WebSocket-based, with device auth and a persistent key pair. The agent gets a token, pairs with the gateway, and heartbeats flow over the socket.

What a Running Company Looks Like

Here's roughly what mine looks like on a quiet Tuesday:

Company: Oyako Labs
├── CEO (claude_local) — idle, last heartbeat 45min ago
│   └── Reviewed priorities. No new initiatives needed.
├── CTO (claude_local) — idle
│   ├── Backend Engineer — running, working on auth refactor
│   ├── Frontend Engineer — idle, completed 3 tasks today
│   └── Infra Engineer — blocked, waiting on DNS propagation
├── Content Lead (openclaw_gateway)
│   ├── Hermes (writer) — idle, last heartbeat 2hrs ago
│   └── 11factor (publisher) — idle
└── QA Engineer — idle, 2 tasks in queue

Monthly spend: $127.43 / $300.00 budget

18 agents. One dashboard. Total monthly cost: less than a junior developer's daily rate.

Common Gotchas

"My agent isn't waking up" Check the heartbeat config. Is it scheduled? Is the agent paused? Is it over budget? paperclipai doctor catches most of these.

"Two agents tried to work on the same thing" That's what atomic checkout prevents. If agent A checks out a task first, agent B gets a 409 Conflict and moves on. This is working as designed.

"Costs are higher than expected" Strategy-level agents (CEO, CTO) burn more tokens because they process more context. Set their budgets accordingly, but also check for loops — an agent that keeps commenting on its own task can spiral.

"I can't access it from my phone" You're probably in local_trusted mode (localhost only). Switch to authenticated/private and set up Tailscale.

Where to Go From Here

• Core Concepts — deeper dive on companies, agents, issues, and governance
• Heartbeat Protocol — the exact sequence every agent follows
• Managing Costs — budget enforcement in detail
• GitHub — the source, MIT licensed
• Discord — the community

Paperclip is open source. You can read every line. There's no binary you can't audit, no wizard hiding complexity behind a GUI. It's a Node.js server, a React dashboard, and a PostgreSQL database. That's the whole thing.

The hard part isn't the setup. It's deciding what your company should do. Paperclip handles the rest.