pnpm dev startup sequence, verifying the Express API at :3100, opening the React dashboard, confirming the Drizzle migration ran, and understanding the console output.
Start the dev servers, walk through the startup sequence output, verify all services are healthy, and understand what every log line means.
cd paperclip
pnpm dev
This runs turbo dev under the hood, which starts all three workspace packages in parallel with interleaved output.
A healthy startup looks like this (colours will vary by terminal):
[server] > paperclip-server@0.1.0 dev
[server] > tsx watch src/index.ts
[web] > paperclip-web@0.1.0 dev
[web] > vite
[server] Connecting to database...
[server] ✓ Using PGlite (dev mode) — data stored at .paperclip/dev.db
[server] Running database migrations...
[server] ✓ Migration complete — 8 tables ready
[web] VITE v5.x.x ready in 312 ms
[web] ➜ Local: http://localhost:5173/
[server] ✓ Heartbeat scheduler started — interval: 60s
[server] ✓ No agents active — scheduler idle
[server] ✓ API listening on http://localhost:3100
What each line means:
| Log line | What it tells you |
|---|---|
Using PGlite |
No DATABASE_URL set — using embedded dev DB |
Migration complete — 8 tables ready |
Schema is up to date |
VITE ready |
Frontend compiled and HMR active |
Scheduler started — interval: 60s |
Heartbeat loop is running |
No agents active — scheduler idle |
Nothing to run yet (expected on first start) |
API listening on :3100 |
Server is ready for requests |
Run these in a second terminal tab to verify everything is working:
curl http://localhost:3100/health
# Expected:
# {"status":"ok","db":"connected","scheduler":"running","uptime":12.3}
Open http://localhost:5173 in your browser.
You should see the Paperclip dashboard with a prompt to create your first company.
pnpm typecheck
# Expected: exits with code 0 (no output = success)
curl http://localhost:3100/api/companies
# Expected: {"data":[],"total":0} (empty — no companies yet)
curl http://localhost:3100/api/heartbeat/status
# Expected: {"running":true,"interval_ms":60000,"next_tick_in_ms":47230}
Server starts but immediately restarts in a loop:
[server] Error: ANTHROPIC_API_KEY is required
Fix: Add ANTHROPIC_API_KEY=sk-ant-... to your .env file.
Port already in use:
[server] Error: listen EADDRINUSE :::3100
Fix:
lsof -i :3100 # find the process
kill -9 <PID> # kill it
pnpm dev stalls after "Running migrations":
This usually means a stale lock on dev.db. Fix:
# Kill pnpm dev (Ctrl+C)
rm .paperclip/dev.db .paperclip/dev.db-wal
pnpm dev
Both the server and the frontend support hot reload:
apps/web/src/ and the browser updates instantly without a page reloadapps/server/src/ and the server restarts automatically (in ~500ms)During server restart, any in-progress heartbeat run is aborted. This is expected in development — the next scheduled tick will retry the run.
Now that everything is running: