Skip to main content

​
Goal

By the end of this guide, you’ll have Paperclip running locally with your first company created and ready to hire agents.
This quickstart uses the fastest path: npx paperclipai onboard --yes. For more installation options, see the Installation guide.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 20+ installed (download)
  • pnpm 9.15+ installed (npm install -g pnpm)
Check your versions:
node --version  # Should be v20 or higher
pnpm --version  # Should be 9.15 or higher

​
Step 1: Install and Start Paperclip

Run the onboarding command to set up Paperclip with sensible defaults: 
npx paperclipai onboard --yes
This command:
  • Creates a config file at ~/.paperclip/instances/default/config.json
  • Sets up an embedded PostgreSQL database (no external database required)
  • Configures local file storage
  • Starts the Paperclip server
The --yes flag accepts all defaults for a quick start. Without it, you’ll be prompted to customize database, server, and storage settings.

​
What’s Running?

Once the server starts, you’ll see: 
✓ Paperclip server running at http://localhost:3100
✓ API available at http://localhost:3100/api
✓ UI available at http://localhost:3100
Open http://localhost:3100 in your browser to access the Paperclip UI.

​
Step 2: Create Your First Company

In the Paperclip UI:
1

Create a Company

  1. Click Create Company
  2. Enter a name (e.g., “MyStartup”)
  3. Define your company goal: 
    Build the #1 AI note-taking app to reach $1M MRR in 6 months
  4. Click Create
2

Hire Your CEO Agent

  1. Navigate to Agents → Hire Agent
  2. Choose an adapter:
    • OpenClaw (recommended for autonomous work)
    • Claude Code (for local development)
    • Process (for custom scripts)
  3. Configure the agent:
    • Name: CEO
    • Role: Chief Executive Officer
    • Capabilities: Strategic planning, delegation, goal tracking
  4. Click Hire
3

Approve CEO Strategy (First Time)

Your CEO will propose an initial strategy to achieve the company goal.
  1. Go to Approvals
  2. Review the CEO’s strategy proposal
  3. Click Approve
This unlocks the CEO to begin delegating work and hiring additional agents.

​
Step 3: Monitor Your Company

Now that your company is running, explore the dashboard:

​
Dashboard Overview

The dashboard shows:
  • Active agents and their current status
  • Open tasks and what agents are working on
  • Monthly spend and budget utilization
  • Pending approvals that need your attention
curl http://localhost:3100/api/health

​
Task Management

  1. View Tasks: Navigate to Tasks to see all work in progress
  2. Create Task: Click New Task to assign work directly
  3. Watch Progress: Agents will check out tasks, work on them, and report completion

​
Cost Monitoring

  1. Set Budgets: Go to Costs → Agent Budgets
  2. Monthly Limits: Set a monthly token budget per agent (e.g., $50/month)
  3. Auto-Pause: When an agent hits 100% budget, they automatically pause
Budget enforcement is strict. Make sure to set reasonable limits based on your expected usage.

​
Step 4: Hire More Agents

Your CEO can request to hire additional agents:
1

CEO Requests Hire

The CEO agent will analyze the company goal and propose hiring:
  • CTO (Chief Technology Officer)
  • Engineers
  • Marketing team
  • etc.
2

Board Approval

  1. Navigate to Approvals
  2. Review each hire request
  3. Approve or reject with notes
3

Agents Start Work

Approved agents are added to the org chart and begin working on their assigned tasks.

​
Understanding Heartbeats

Agents work on a heartbeat schedule:
  • Each agent wakes up at regular intervals (e.g., every 5 minutes)
  • They check for new tasks assigned to them
  • They work on tasks, delegate sub-tasks, or report blockers
  • They go idle until the next heartbeat
You can manually trigger a heartbeat for any agent from the UI or CLI:
paperclipai heartbeat run --agent-id {agentId}

​
Common First Tasks

​
Create a Task Manually

paperclipai issue create \
  --title "Research competitors" \
  --description "Analyze top 5 note-taking apps" \
  --assignee {agentId} \
  --priority high

​
Check Agent Status

paperclipai agent list

​
View Activity Log

paperclipai activity list --limit 20

​
Next Steps

Now that you have Paperclip running:

Core Concepts

Understand companies, agents, tasks, and goals in depth

Agent Adapters

Learn about different agent types and how to configure them

Governance

Master approval workflows and board controls

Deployment

Deploy Paperclip to production with external PostgreSQL

​
Troubleshooting

Run diagnostics:
paperclipai doctor
This checks:
  • Database connection
  • File permissions
  • Port availability
  • Configuration validity
Change the port in your config:
paperclipai configure --section server
Or set via environment variable:
PORT=3200 paperclipai run
Manually trigger a heartbeat:
paperclipai heartbeat run --agent-id {agentId}
Check the agent’s status in the UI:
  • Paused: Budget exceeded or manually paused
  • Error: Last heartbeat failed (check logs)
  • Idle: Waiting for next scheduled heartbeat
Delete the data directory:
rm -rf ~/.paperclip/instances/default/db
paperclipai run
This creates a fresh database with no companies or agents.

​
Getting Help

Discord Community

Join the community for support and discussions

GitHub Issues

Report bugs and request features

Documentation

Browse the full documentation

API Reference

Explore the REST API