Paperclip — Open-Source Agent Orchestration for the AI Workplace
Paperclip — Open-Source Agent Orchestration for the AI Workplace
If you've been following the AI agent space, you've noticed a pattern: everyone builds agents, but nobody has a good way to manage them at scale. You start with one Claude Code terminal, then two, then twenty — and suddenly you're babysitting agents instead of getting work done.
Paperclip solves this by treating your agents like employees. It's an open-source orchestration platform (Node.js + React) that gives you org charts, ticketing, budgets, governance, and heartbeats — all from one dashboard. Think of it as the "company" that hires your agents.
At 71K+ GitHub stars and MIT-licensed, Paperclip is one of the fastest-growing tools in the AI infrastructure space. Let's explore what it does and how to get it running.
Architecture Overview
At the top, the React UI Dashboard gives you a task-manager-like interface where you manage goals, monitor budgets, and approve governance decisions. Below it, the Paperclip Server is the core orchestrator — it handles identity and access, maintains the org chart and agent registry, manages the work and task system with atomic checkout, executes heartbeats on a wake-up queue, enforces governance and approval gates, and tracks budgets and costs. A PostgreSQL database (embedded for dev, external for production) stores all state. The Plugin System extends Paperclip with out-of-process workers, and the Agent Adapters layer connects to any runtime that can receive a heartbeat — Claude Code, Codex, CLI agents (Cursor, Gemini, bash), and HTTP/web bots (OpenClaw, webhooks).
The key insight: Paperclip doesn't build agents — it orchestrates them. You bring your own agents and Paperclip gives them an org chart, a task system, and cost controls.
Why It's Trending
Paperclip hit GitHub trending in early 2026 and hasn't slowed down. Here's why:
- 71K+ stars in 3 months — explosive organic adoption from the AI agent community
- Multi-agent orchestration gap — every other tool focuses on building agents; Paperclip focuses on managing them
- BYO agent model — bring Claude Code, Codex, Cursor, OpenClaw, or any HTTP-callable agent
- Enterprise features out of the box — org charts, budgets, governance, audit trails, multi-company isolation
- Self-hosted, no vendor lock-in — runs entirely on your infrastructure
- Active development — daily commits, Discord community, and an ambitious roadmap
Prerequisites
- Node.js 20+ — the server runtime
- pnpm 9.15+ — package manager
- A modern browser for the dashboard
- (Optional) Docker and PostgreSQL for production deployment
Getting Started with Paperclip
Quickstart (Single Command)
Paperclip offers a one-command onboarding experience:
npx paperclipai onboard --yesThis clones the repo, installs dependencies, starts the API server at http://localhost:3100, and creates an embedded PostgreSQL database automatically — no setup required.
Troubleshooting: If you use a private npm registry (e.g., GitHub Packages),
npxmay try to resolvepaperclipaiagainst it. Force the public registry:npx --registry https://registry.npmjs.org paperclipai onboard --yes
Manual Setup
If you prefer manual control:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm devThe API server starts at http://localhost:3100. Open the URL in your browser to access the dashboard.
Running on a Network
For team access or phone monitoring:
npx paperclipai onboard --yes --bind lan
# Or via Tailscale:
npx paperclipai onboard --yes --bind tailnetProduction Deployment with Docker Compose
Paperclip works well behind a reverse proxy with an external PostgreSQL. Here's a production docker-compose.yml:
version: "3.8"
services:
paperclip:
image: node:20-slim
container_name: paperclip
restart: unless-stopped
working_dir: /app
ports:
- "3100:3100"
environment:
- DATABASE_URL=postgresql://paperclip:password@db:5432/paperclip
- NODE_ENV=production
- PAPERCLIP_TELEMETRY_DISABLED=1
volumes:
- ./paperclip:/app
- /app/node_modules
command: sh -c "pnpm install && pnpm build && pnpm start"
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
container_name: paperclip-db
restart: unless-stopped
environment:
POSTGRES_USER: paperclip
POSTGRES_PASSWORD: password
POSTGRES_DB: paperclip
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U paperclip"]
interval: 5s
timeout: 5s
retries: 5
volumes:
pgdata:Configuration
Paperclip stores its configuration in a local file after the first run. Key settings include:
| Setting | Purpose |
|---|---|
--bind lan |
Bind to LAN interface for network access |
--bind tailnet |
Bind to Tailscale interface |
PAPERCLIP_TELEMETRY_DISABLED=1 |
Disable anonymous usage telemetry |
DATABASE_URL |
External PostgreSQL connection string |
DO_NOT_TRACK=1 |
Alternative telemetry opt-out |
To edit settings after onboarding:
npx paperclipai configureWorking with Paperclip
Once Paperclip is running, the workflow is straightforward:
- Define a goal — e.g., "Build the #1 AI note-taking app to $1M MRR"
- Hire your team — Add Claude Code, Codex, or any agent as employees with roles, titles, and budgets
- Approve and run — Review strategy, set budgets, hit go
- Monitor from the dashboard — Track costs, audit work, chime in when needed
Key Concepts
Heartbeats — Agents don't run continuously. They wake on a schedule (heartbeat), check their assigned tasks, do work, and sleep. Heartbeats can be triggered by cron schedules, webhooks, or API calls.
Org Chart — Agents have a boss, a title, a job description, and a budget. Delegation flows up and down the hierarchy.
Budget & Cost Control — Every agent has a monthly budget cap. When they hit it, they stop. No runaway token costs.
Governance — Approval gates, execution policies, and full audit trails. Nothing ships without your sign-off.
Verification Checklist
After setup, run through these checks:
- Dashboard accessible at
http://localhost:3100 - Can create a company and add agents
- Can define a goal and assign tasks
- Agent heartbeat executes (check activity log)
- Budget limits are enforced (set a low cap and verify the agent stops)
Resources
- GitHub: https://github.com/paperclipai/paperclip
- Documentation: https://paperclip.ing/docs
- Website: https://paperclip.ing
- Discord: https://discord.gg/m4HZY7xNG3
- Twitter / X: https://x.com/papercliping
- Plugin Ecosystem: https://github.com/gsxdsm/awesome-paperclip