Installation & Quick Start

npx paperclipai onboard --yes for zero-config start, git clone + pnpm dev for contributors, and Docker Compose for isolated runs. Prerequisites: Node 20+, pnpm 9.15+.

Installation & Quick Start

What you'll build

A running Paperclip AI instance using the install path that fits your situation — zero-config onboarding, developer clone, or Docker Compose.

Prerequisites

Node.js 20+ (node --version)
pnpm 9.15+ (pnpm --version)
An Anthropic API key (get one at console.anthropic.com)

Path A — Zero-config onboarding (fastest)

If you just want to try Paperclip immediately without cloning anything:

npx paperclipai onboard --yes

This command:
1. Downloads the latest Paperclip server to a temp directory
2. Prompts for your ANTHROPIC_API_KEY
3. Starts the API on port 3100 and opens the dashboard
4. Creates a default company and a sample agent

Best for: Evaluating Paperclip, demos, proof of concept.
Not for: Development, customization, or production.

Path B — Developer clone (recommended)

For building with Paperclip or contributing to it:

# 1. Clone
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# 2. Install workspace dependencies
pnpm install

# 3. Configure
cp .env.example .env
# Edit .env — set ANTHROPIC_API_KEY at minimum

# 4. Start all services
pnpm dev

Services that start:

Service	URL	Purpose
API server	http://localhost:3100	REST API + heartbeat scheduler
Web dashboard	http://localhost:5173	React frontend
PGlite	(in-process)	Dev database, no setup needed

Path C — Docker Compose

For an isolated, production-like environment on your local machine:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# Create your env file
cp .env.example .env
# Edit .env with your API keys

# Build and start all containers
docker compose up --build

Docker Compose starts:
- paperclip-server — API on port 3100
- paperclip-web — Frontend on port 5173
- postgres — Real PostgreSQL on port 5432 (data persisted in a Docker volume)

Best for: Teams, staging environments, reproducible dev setups.

Verifying the installation

After any install path, confirm everything is healthy:

# 1. API health check
curl http://localhost:3100/health
# Expected: {"status":"ok","db":"connected","scheduler":"running"}

# 2. Check the dashboard loads
open http://localhost:5173
# You should see the Paperclip dashboard with a "Create Company" prompt

Common setup errors

Error	Cause	Fix
`EADDRINUSE :3100`	Port already in use	`lsof -i :3100` then kill the process
`Invalid API key`	Wrong ANTHROPIC_API_KEY	Check console.anthropic.com → API Keys
`pnpm: command not found`	pnpm not installed	`npm install -g pnpm`
`Cannot find module`	pnpm install incomplete	`rm -rf node_modules && pnpm install`
DB migration error	Leftover dev.db from old version	`rm .paperclip/dev.db && pnpm dev`

Next steps after installation

Once running, your immediate next steps are:

Open the dashboard at http://localhost:5173
Create your first company (next module)
Set up .env with any additional adapter API keys you want (OpenAI, etc.)

Checkpoint ✓

Which install path is best for development vs. evaluation?
What is the API health check endpoint?
What does the Docker Compose setup add that Path B doesn't have?
How do you fix an EADDRINUSE error on port 3100?