How to Set Up Paperclip for Local Development with Embedded PGlite

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 source code.

Prerequisites and Installation

Getting started requires minimal tooling. According to 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:

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【/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.

When DATABASE_URL is not set, the resolveDatabaseTarget() function in 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【/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 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【/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 (legacy name) or embeddedPostgresDataDir (current name). Similarly, override the default port with pglitePort or embeddedPostgresPort. The CLI configuration in 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:

# 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【/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:

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【/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:

# 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【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L62-L70】.

Complete Command Reference

# 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	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	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	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	Prerequisites, data directory details, mobile preview, and Tailscale mode【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L47-L70】
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
• 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 from @electric-sql/pglite as a dependency. When DATABASE_URL is unset, the runtime in 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【/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. Legacy field names pgliteDataDir and pglitePort are automatically migrated to the current names by the logic in 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【/cache/repos/github.com/paperclipai/paperclip/master/doc/DEVELOPING.md#L48-L55】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}