> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinkingmach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

Run Paperclip locally with zero external dependencies.

## Prerequisites

* Node.js 24.11+
* pnpm 9+

## Start Dev Server

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
pnpm dev --bind lan
```

For Tailscale-only binding on a detected tailnet address:

```sh theme={null}
pnpm dev --bind tailnet
```

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

```sh theme={null}
pnpm dev --tailscale-auth
pnpm dev --authenticated-private
```

Allow additional private hostnames:

```sh theme={null}
npx paperclipai allowed-hostname dotta-macbook-pro
```

For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).

## Health Checks

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
# 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:

```sh theme={null}
npx paperclipai worktree:cleanup local-lab --force
```

## Reset Dev Data

To wipe local data and start fresh:

```sh theme={null}
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:

```sh theme={null}
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
```