# How to Set Up Paperclip for Local Development with Embedded PGlite

> Set up Paperclip for local development with embedded PGlite. Run Paperclip locally without an external database for seamless testing. Learn the simple development setup.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Paperclip's development mode runs entirely locally using an embedded PostgreSQL database via the @electric-sql/pglite package when `DATABASE_URL` is unset—no external database required.**

This guide walks through the complete **development setup for Paperclip with embedded PGlite**, covering prerequisites, configuration flow, database lifecycle, and advanced networking modes. Everything here is grounded in the actual [paperclipai/paperclip](https://github.com/paperclipai/paperclip) source code.

## Prerequisites and Installation

Getting started requires minimal tooling. According to [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md), you need:

- **Node.js 20+**
- **pnpm 9+**

No Docker, no external PostgreSQL installation, and no manual PGlite setup are required. The embedded database is pulled automatically as a dependency.

Install and start the stack with one command chain:

```bash
pnpm install && pnpm dev

```

This installs dependencies and starts both the **API server** and **UI** in the same process. The UI is served through the API server's development middleware. The server listens on `http://localhost:3100`, with the UI reachable at the same address. This workflow is documented in the *Dev Setup (Auto DB)* section of [`AGENTS.md`](https://github.com/paperclipai/paperclip/blob/main/AGENTS.md)【/cache/repos/github.com/paperclipai/paperclip/master/AGENTS.md#L38-L51】.

## How the Embedded PGlite Auto-Configuration Works

Paperclip's runtime detects the development environment through a configuration hierarchy: **environment variables > `.env` file > [`config.json`](https://github.com/paperclipai/paperclip/blob/main/config.json)**.

When `DATABASE_URL` is **not set**, the `resolveDatabaseTarget()` function in [`packages/db/src/runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/runtime-config.ts) automatically selects **embedded-postgres** mode. This function:

1. Determines a data directory for database files
2. Assigns an available port
3. Migrates any legacy `pglite` settings to the new `embedded-postgres` naming

The mapping logic from legacy `pglite` to `embedded-postgres` mode lives at lines 114-128 of [`runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/runtime-config.ts)【/cache/repos/github.com/paperclipai/paperclip/master/packages/db/src/runtime-config.ts#L114-L128】. For example, deprecated `pgliteDataDir` and `pglitePort` fields in [`config.json`](https://github.com/paperclipai/paperclip/blob/main/config.json) are automatically translated to `embeddedPostgresDataDir` and `embeddedPostgresPort`.

## Default Data Directory and Persistence

By default, the embedded PGlite instance stores its files in the user's Paperclip home directory:

```

~/.paperclip/instances/default/db

```

This location is documented in the *Database in Dev* section of [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md)【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L47-L53】. Database state persists across restarts, so your data survives `pnpm dev` invocations.

To use a custom location, specify `pgliteDataDir` in [`config.json`](https://github.com/paperclipai/paperclip/blob/main/config.json) (legacy name) or `embeddedPostgresDataDir` (current name). Similarly, override the default port with `pglitePort` or `embeddedPostgresPort`. The CLI configuration in [`cli/src/config/store.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/store.ts) mirrors this runtime conversion at lines 57-68【/cache/repos/github.com/paperclipai/paperclip/master/cli/src/config/store.ts#L57-L68】, ensuring commands like `paperclipai run` respect your settings.

## Resetting the Development Database

To completely reset your local development database, delete the PGlite data folder and restart:

```bash

# Default user-home location

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

# Or repository-relative location (if configured)

rm -rf data/pglite

# Then restart

pnpm dev

```

This reset procedure appears in the *Reset local dev DB* snippet of [`AGENTS.md`](https://github.com/paperclipai/paperclip/blob/main/AGENTS.md)【/cache/repos/github.com/paperclipai/paperclip/master/AGENTS.md#L59-L64】.

## Mobile-Friendly and Networked Development Modes

Paperclip provides several dev server variants for different testing scenarios:

### Mobile Preview Mode

Test on actual devices or simulate low-bandwidth conditions:

```bash
pnpm dev:mobile

```

This builds a production-optimized UI bundle and serves it on port `:3101`, proxying API calls to the dev server. Documented in [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md)【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L48-L55】.

### LAN and Tailscale Bindings

Run in **authenticated/private mode** while still using embedded PGlite:

```bash

# Accessible on your local network

pnpm dev --bind lan

# Accessible via Tailscale network

pnpm dev --bind tailnet

```

These modes enable team collaboration or remote device testing without exposing unauthenticated endpoints. See the *Tailscale/private-auth dev mode* section of [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md)【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L62-L70】.

## Complete Command Reference

```bash

# Standard development (embedded PGlite, local only)

pnpm install && pnpm dev

# Verify the server is healthy

curl http://localhost:3100/api/health

# List companies (requires initial setup)

curl http://localhost:3100/api/companies

# Mobile production preview

pnpm dev:mobile

# Network-accessible with authentication

pnpm dev --bind lan
pnpm dev --bind tailnet

# Full database reset

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

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`packages/db/src/runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/runtime-config.ts) | Core logic for detecting `DATABASE_URL` absence and resolving embedded-postgres targets; includes legacy-to-current setting migration【/cache/repos/github.com/paperclipai/paperclip/master/packages/db/src/runtime-config.ts#L114-L128】 |
| [`cli/src/config/store.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/store.ts) | CLI-side configuration handling that mirrors runtime conversion for commands like `paperclipai run`【/cache/repos/github.com/paperclipai/paperclip/master/cli/src/config/store.ts#L57-L68】 |
| [`AGENTS.md`](https://github.com/paperclipai/paperclip/blob/main/AGENTS.md) | Primary documentation for dev setup, auto-database behavior, and reset procedures【/cache/repos/github.com/paperclipai/paperclip/master/AGENTS.md#L38-L64】 |
| [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md) | Prerequisites, data directory details, mobile preview, and Tailscale mode【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L47-L70】 |
| [`README.md`](https://github.com/paperclipai/paperclip/blob/main/README.md) | Quickstart overview noting automatic embedded PostgreSQL creation【/cache/repos/github.com/paperclipai/paperclip/master/README.md#L71-L78】 |

## Summary

- **Zero external dependencies**: Node 20+ and pnpm 9+ are all you need; PGlite is embedded via `@electric-sql/pglite`
- **Automatic detection**: Unset `DATABASE_URL` triggers embedded-postgres mode through `resolveDatabaseTarget()` in [`runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/runtime-config.ts)
- **Persistent data**: Default location at `~/.paperclip/instances/default/db`, customizable via config
- **Simple reset**: Delete the data folder and restart `pnpm dev`
- **Flexible networking**: Standard local dev, mobile preview (`pnpm dev:mobile`), or authenticated LAN/Tailscale modes

## Frequently Asked Questions

### Do I need to install PostgreSQL separately for Paperclip development?

No. Paperclip bundles [PGlite](https://github.com/electric-sql/pglite) from `@electric-sql/pglite` as a dependency. When `DATABASE_URL` is unset, the runtime in [`packages/db/src/runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/db/src/runtime-config.ts) automatically instantiates an embedded PostgreSQL-compatible database. No system PostgreSQL installation, Docker container, or manual PGlite setup is required.

### How do I reset my development database to a clean state?

Delete the PGlite data directory and restart. The default location is `~/.paperclip/instances/default/db` (or `data/pglite` if using repository-relative paths). Run `rm -rf ~/.paperclip/instances/default/db` followed by `pnpm dev`. This is documented in [`AGENTS.md`](https://github.com/paperclipai/paperclip/blob/main/AGENTS.md)【/cache/repos/github.com/paperclipai/paperclip/master/AGENTS.md#L59-L64】.

### Can I use a custom port or data directory for the embedded database?

Yes. Add `embeddedPostgresDataDir` and/or `embeddedPostgresPort` to your [`config.json`](https://github.com/paperclipai/paperclip/blob/main/config.json). Legacy field names `pgliteDataDir` and `pglitePort` are automatically migrated to the current names by the logic in [`runtime-config.ts`](https://github.com/paperclipai/paperclip/blob/main/runtime-config.ts) lines 114-128【/cache/repos/github.com/paperclipai/paperclip/master/packages/db/src/runtime-config.ts#L114-L128】.

### What is the difference between `pnpm dev` and `pnpm dev:mobile`?

`pnpm dev` runs the API server and UI development middleware together on port 3100. `pnpm dev:mobile` builds a production UI bundle and serves it on port 3101 with API calls proxied to the dev server—useful for testing on physical devices or simulating production performance. Mobile mode is described in [`doc/DEVELOPING.md`](https://github.com/paperclipai/paperclip/blob/main/doc/DEVELOPING.md)【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L48-L55】.