Run Paperclip locally with zero external dependencies.

​
Prerequisites

  • Node.js 20+
  • pnpm 9+

​
Fastest Path

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.

​
Operator Defaults

  • Use local_trusted unless you specifically need network access.
  • Keep HOST=127.0.0.1 for the default local dev loop.
  • Use authenticated + private only when you need Tailscale, VPN, or LAN access.
  • Use PAPERCLIP_PUBLIC_URL only when the browser origin should be stable across restarts or remote devices.

​
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. Alias: 
pnpm dev --authenticated-private
Allow additional private hostnames: 
pnpm paperclipai allowed-hostname dotta-macbook-pro
For full setup and troubleshooting, see Tailscale Private Access.

​
Local Compose

If you want a Docker-backed local environment instead of the embedded database path, use docker.md.

​
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

​
Recovery Shortcut

If local dev gets wedged, start with ../RECOVERY.md. That playbook covers DB reset, port conflicts, and stale watcher state.