Local Development Environment Setup

Full local dev walkthrough: Node 20+ via nvm, pnpm 9.15+, cloning the repo, .env configuration, recommended VS Code extensions (ESLint, Drizzle), hot-reload with pnpm dev, and verifying all services are healthy.

Local Development Environment Setup

What you'll build

A fully working Paperclip AI development environment on your local machine — Node.js, pnpm, VS Code extensions, and a verified installation where all three services (API, frontend, database) start cleanly.

Prerequisites

macOS, Linux, or Windows (WSL2 recommended on Windows)
4 GB RAM minimum (8 GB recommended)
Basic terminal comfort

Step 1 — Install Node.js 20 via nvm

Paperclip requires Node.js 20 LTS. The easiest way to manage Node versions is nvm.

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart terminal, then:
nvm install 20
nvm use 20
nvm alias default 20

Verify:

node --version   # v20.x.x
npm --version    # 10.x.x

Windows users: Install nvm-windows instead, then run the same nvm install 20 command in PowerShell.

Step 2 — Install pnpm 9.15+

Paperclip uses pnpm (not npm or yarn) as its package manager. pnpm is faster and uses a shared content-addressable store to avoid duplicate packages.

npm install -g pnpm@latest

# Verify
pnpm --version   # 9.15.x or higher

Step 3 — Clone the repository

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

# Install all workspace dependencies
pnpm install

pnpm will install packages for all three workspaces: apps/server, apps/web, and packages/.

Step 4 — Configure environment variables

Copy the example env file and fill in your API keys:

cp .env.example .env

Open .env and set the values you need:

# Required: at least one adapter key
ANTHROPIC_API_KEY=sk-ant-...       # for Claude Code adapter
OPENAI_API_KEY=sk-...              # for OpenAI adapter (optional)

# Database (defaults to PGlite in dev — no setup needed)
DATABASE_URL=                      # leave blank to use embedded PGlite

# Server
PORT=3100
HEARTBEAT_INTERVAL_MS=60000        # how often the scheduler ticks (1 min)

# Frontend
VITE_API_URL=http://localhost:3100

ANTHROPIC_API_KEY is the only truly required key for the default Claude Code adapter. Everything else has a working default for local dev.

Step 5 — Recommended VS Code extensions

Open VS Code in the project root (code .) and install:

Extension	Why
ESLint	Catches TypeScript and style issues as you type
Prettier	Formats code on save to match project style
Drizzle ORM	Schema introspection and query hints
Thunder Client	REST API testing inside VS Code
GitLens	Better git blame and history

Step 6 — Start the development servers

pnpm dev

This starts three processes in parallel:
1. apps/server — Express API on port 3100
2. apps/web — Vite dev server on port 5173
3. The Drizzle migration runs automatically on first start

What healthy output looks like:

[server] ✓ Database migrated (8 tables)
[server] ✓ Scheduler started — interval: 60s
[server] ✓ API listening on http://localhost:3100
[web]    ✓ Local:   http://localhost:5173/

If you see any EADDRINUSE error, another process is on port 3100 or 5173. Run lsof -i :3100 to find and kill it.

Step 7 — Verify the 5 health checks

Check	How
API is up	`curl http://localhost:3100/health` → `{"status":"ok"}`
DB migrated	Server log shows "8 tables" on startup
Frontend loads	Open http://localhost:5173 in browser
Scheduler running	Server log shows "Scheduler started"
No TS errors	`pnpm typecheck` exits with code 0

Checkpoint ✓

Node 20, pnpm 9.15+, and the repo are installed
.env has your ANTHROPIC_API_KEY
pnpm dev starts cleanly with all 3 services
curl localhost:3100/health returns {"status":"ok"}