Local Development

Run Paperclip locally with zero external dependencies.

Prerequisites

• Node.js 24.11+
• 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

Bind Presets In Dev

Default pnpm dev stays in local_trusted with loopback-only binding.

To open Paperclip to a private network with login enabled:

pnpm dev --bind lan

For Tailscale-only binding on a detected tailnet address:

pnpm dev --bind tailnet

Legacy aliases still work and map to the older broad private-network behavior:

pnpm dev --tailscale-auth
pnpm dev --authenticated-private

Allow additional private hostnames:

npx paperclipai allowed-hostname dotta-macbook-pro

For full setup and troubleshooting, see Tailscale Private Access.

Health Checks

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

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

Safe Worktree Bootstrap for Local Agent Runs

For safer parallel local experiments, initialize a dedicated worktree instance instead of reusing your main checkout:

npx paperclipai worktree:make local-lab --seed-mode minimal
cd ~/paperclip-local-lab
pnpm paperclipai worktree env                       # inspect generated env exports
eval "$(npx paperclipai worktree env)"             # bash/zsh
pnpm paperclipai run
pnpm paperclipai doctor

If the experiment gets noisy, repair or reseed the worktree without touching the main branch:

# worktree repair rebuilds the local checkout metadata, so run the checked-out CLI through the direct-exec form.
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts worktree repair --branch paperclip-local-lab
npx paperclipai worktree reseed --from . --to paperclip-local-lab

When done, shut it down and remove the isolated state explicitly:

npx paperclipai worktree:cleanup local-lab --force

Reset Dev Data

To wipe local data and start fresh:

rm -rf ~/.paperclip/instances/default/db
pnpm dev

Data Locations

Data	Path
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