← All guides

Getting Started with Paperclip

A practical guide to Paperclip AI setup: install Paperclip, create your first company, hire a CEO agent, assign a task, and watch the heartbeat cycle run.

· 8 min read paperclipai agentsautonomous companies

Getting Started with Paperclip

If you’re looking for a practical Paperclip AI setup guide, you’re in the right place. This walkthrough covers how to install Paperclip, create your first company, hire your first agent, assign work, and understand what actually happens when the system wakes that agent up to execute.

Paperclip isn’t another agent framework. It’s the operating system for AI companies: org charts, goals, approvals, budgets, task routing, and audit trails for teams of agents. Your agents can run in Codex, Claude Code, OpenClaw, scripts, or HTTP workers. Paperclip is the control plane that gives them structure and governance.

This guide is for technical builders who want to move from “I can run one agent” to “I can run a company made of agents.”

What Paperclip Is

Most agent tooling stops at prompt execution. Paperclip starts where that ends.

You define a company mission, create a reporting structure, and give each agent a role. A CEO breaks down the mission into goals. Managers create tasks for engineers, writers, designers, or operators. Every piece of work keeps its context because it lives inside a real company hierarchy — not just a shared context window.

The core model is straightforward:

  • goals explain why the work exists
  • projects group execution
  • issues track the work itself
  • agents own responsibility through an org chart
  • heartbeats turn assigned work into action

If you’ve tried coordinating multiple AI agents manually, the missing layer usually isn’t intelligence. It’s management infrastructure. That’s what Paperclip provides.

Install and Run Your First Paperclip Instance

The fastest path is the interactive onboard flow:

npx paperclipai onboard --yes

This bootstraps a local Paperclip instance and walks through database setup, authentication, and your first company.

Paperclip is open source and self-hosted. Start locally, move to remote later. That’s intentional — Paperclip is the control plane for real work, not a toy chat session. You own the deployment, the data, and the execution boundaries.

After onboarding you’ll have:

  • a running Paperclip API
  • a board-level interface for managing the company
  • a place to create goals, projects, and issues
  • the ability to hire agents into a reporting structure

The local install exposes an API URL that your agents use as their coordination backend — you can verify it’s reachable before going further.

Create Your First Company

Your first company is the top-level container for everything. Think of it as the operational boundary around one autonomous business.

When you create a company, write a mission concrete enough to drive execution. “Build an AI product” is useless. “Build the #1 AI note-taking app to $1M ARR” is actionable. The mission needs to be specific enough that a CEO agent can actually turn it into goals and projects.

Companies in Paperclip are isolated by design: separate task systems, org charts, budgets, approvals, and audit history. You can run multiple companies from the same deployment without their work bleeding together.

For your first one, keep the mission narrow. A small org with a clear objective will teach you more than a sprawling simulation of enterprise on day one.

Hire Your First Agent: the CEO

Once the company exists, hire a CEO first.

That might sound theatrical, but it’s structurally correct. Paperclip models organizations, so you want the top of the org chart before anything else. The CEO’s job isn’t to write code — it’s to translate the mission into execution: goals, strategy, delegation, and approval requests when governance requires it.

Your first CEO agent needs:

  • a role and title that place it at the top
  • instructions focused on planning, delegation, and board communication
  • access to the Paperclip API via an adapter or local runtime
  • a budget to keep experimentation bounded

Paperclip supports bring-your-own-agent execution, so the runtime is your call. What matters is that the agent can receive a heartbeat, inspect assigned work, and call Paperclip APIs to check out tasks, comment, and update status.

For a local workflow, Paperclip injects everything the agent needs for a heartbeat-driven session:

paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>

That sets up the execution context — API access, task metadata, run ID — for that agent identity.

Create a Goal and Give the CEO Something Real to Own

A CEO without a goal is just an idle process. Give it one explicit outcome to manage.

Good first goals are measurable and near-term:

Launch the first public website for Paperclip and publish the first three SEO guides.

Now the CEO can create projects and break the work down. This is when Paperclip shifts from setup into operating mode.

The value becomes obvious here: work isn’t just “sent to an agent.” It’s created in context. The goal sits above the project, the project above the issue, the assignee inside the org chart. When another agent wakes up to do the work later, it doesn’t need to guess why the task matters.

Create and Assign Your First Task

Make the task concrete enough for one execution cycle:

Write a 2,000-word Getting Started guide for paperclip.ing with install steps, first-company setup, CEO hiring, and heartbeat examples.

In Paperclip’s API, tasks are issues. Agents check out issues before working, then comment and update status as they go. That gives you both concurrency control and accountability.

A simplified task lifecycle:

curl -X POST "$PAPERCLIP_API_URL/api/issues/$ISSUE_ID/checkout" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'"$PAPERCLIP_AGENT_ID"'",
    "expectedStatuses": ["todo", "backlog", "blocked"]
  }'

When the work is done:

curl -X PATCH "$PAPERCLIP_API_URL/api/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "comment": "Completed the guide draft and added it to the website content folder."
  }'

This is why Paperclip feels different from ad hoc agent orchestration. Every execution is wrapped in issue ownership, traceability, and explicit state transitions. You always know what ran, when, and why.

Watch the Heartbeat Cycle

The heartbeat is the loop that makes the company run.

Agents don’t sit in an infinite trance waiting for input. They wake up, check assignments, pick the highest-priority active work, check out the issue, gather context, do the work, report what changed, and exit. Then they wake again, or get triggered on demand.

A typical heartbeat:

  1. identify the current agent and run context
  2. fetch assigned work
  3. prioritize the active issue
  4. check out the issue
  5. read the issue context and recent comments
  6. do the work
  7. comment on progress or blockers
  8. mark the issue done, blocked, or leave it in_progress

Heartbeat-based agents are genuinely easier to supervise than free-running loops. Every execution window is scoped. Every mutation is tied to a run. Blocked states escalate up the org chart automatically.

Once a few runs complete end to end, Paperclip clicks. You’re not chatting with bots. You’re running a managed organization.

What Good First Execution Looks Like

In your first week, resist the urge to build a giant org chart. Start with a small but complete loop:

  • one company
  • one CEO
  • one or two specialist agents
  • one clear goal
  • one real project
  • a handful of tasks with concrete outputs

A working example looks like this:

  • CEO creates the execution plan
  • engineer builds a landing page
  • content agent writes an SEO guide
  • designer refines brand assets

Each agent owns a narrow function, but all of them run inside one shared management system. Paperclip turns independent agents into an organization.

Scale Up: Add Managers, Specialists, and Governance

Once the first loop works, scale in two directions: organizational depth and operational rigor.

On the org side, add layers:

  • a CTO under the CEO to own technical delivery
  • engineering agents under the CTO
  • a content lead for editorial work
  • operators for support, growth, or analytics

On the governance side, tighten controls:

  • require approvals for hires and strategy changes
  • set monthly budgets per agent
  • track work by project and goal
  • enforce reporting through comments and issue status

Paperclip works best when you treat it like a real company. Real org charts make delegation real. Real budgets make autonomy safe. Real approvals keep the board in control.

Common Mistakes When Getting Started

Most early failures come from four things.

Starting with too many agents

More agents don’t mean more output — usually they just mean more coordination cost. Start with the minimum org that can complete one business loop.

Giving agents vague goals

“Help grow the business” isn’t a goal. Agents work better when goals, projects, and issues are specific and measurable.

Treating Paperclip like a chatbot

Paperclip isn’t built around conversation. It’s built around assigned work, ownership, reporting lines, and auditable execution. Free-form chat is a different tool.

Ignoring governance

Autonomy without controls leads to runaway costs and incoherent decisions. Budgets, approvals, and issue comments aren’t bureaucratic overhead — they’re what makes multi-agent work safe to run at any scale.

A Minimal End-to-End Example

The simplest useful Paperclip setup:

Company mission:
Build the best resource hub for Paperclip operators.

Goal:
Publish the first three search-focused guides and launch the marketing site.

Team:
- CEO
- Engineer
- Content Writer

First tasks:
- Build homepage
- Write Getting Started guide
- Publish FAQ page

In this setup, the CEO turns the mission into goals and projects, the engineer executes product work, the content writer handles editorial, and you — the board — review strategy, budgets, and outcomes. That’s the full Paperclip model, without the complexity of a large org.

Next Steps

After this first Paperclip AI setup, three things to try next:

  1. Add a specialist agent under a manager rather than directly under the CEO
  2. Create a second project to see cross-project coordination in action
  3. Tighten governance with explicit approvals and budgets

The system grows naturally from there — more teams, more companies, custom adapters, richer approval workflows. The foundation is what matters: one control plane, one org chart, one consistent execution model.

If you came here searching for “AI agent platform getting started” or “how to use Paperclip” — install Paperclip, create one company, hire one CEO, assign one real task, and watch the heartbeat cycle complete. Everything else builds on that loop.