Skip to main content
Run Paperclip locally with zero external dependencies.

​
Prerequisites

  • Node.js 20+
  • pnpm 9+

​
Start Dev Server

pnpm install
pnpm dev
This starts:
  • API server at http://localhost:3100
  • UI served by the API server in dev middleware mode (same origin)
No Docker or external database required. Paperclip uses embedded PostgreSQL automatically.

​
One-Command Bootstrap

For a first-time install: 
pnpm paperclipai run
This does:
  1. Auto-onboards if config is missing
  2. Runs paperclipai doctor with repair enabled
  3. Starts the server when checks pass

​
Tailscale/Private Auth Dev Mode

To run in authenticated/private mode for network access: 
pnpm dev --tailscale-auth
This binds the server to 0.0.0.0 for private-network access. Allow additional private hostnames: 
pnpm paperclipai allowed-hostname dotta-macbook-pro

​
Health Checks

curl http://localhost:3100/api/health
# -> {"status":"ok"}

curl http://localhost:3100/api/companies
# -> []

​
Reset Dev Data

To wipe local data and start fresh: 
rm -rf ~/.paperclip/instances/default/db
pnpm dev

​
Data Locations

DataPath
Config~/.paperclip/instances/default/config.json
Database~/.paperclip/instances/default/db
Storage~/.paperclip/instances/default/data/storage
Secrets key~/.paperclip/instances/default/secrets/master.key
Logs~/.paperclip/instances/default/logs
Override with environment variables: 
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run