# What Is `pnpm dev` in Paperclip? A Deep Dive Into the Local Development Runtime

> Discover how pnpm dev in Paperclip AI powers your local development. This command starts the API, UI, manages databases, and restarts automatically.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: deep-dive
- Published: 2026-08-14

---

**`pnpm dev` is the single command that launches Paperclip's complete local development environment, starting both the API server and React UI while handling database setup, file watching, auto-restart, and migration management automatically.**

In the `paperclipai/paperclip` repository, this command serves as the central entry point for developers building on or extending the platform. Rather than manually orchestrating multiple services, developers rely on `pnpm dev` to mirror production behavior—including service registration, health checks, and schema migrations—while maintaining a fast feedback loop through hot reloading.

## What `pnpm dev` Actually Starts

When you run `pnpm dev` from the repository root, the orchestration logic in [`scripts/dev-runner.ts`](https://github.com/paperclipai/paperclip/blob/main/scripts/dev-runner.ts) initializes several interconnected systems.

### API Server and React UI on a Unified Port

The command binds both backend and frontend to `http://localhost:3100` by default, as documented in [`docs/start/quickstart.md`](https://github.com/paperclipai/paperclip/blob/main/docs/start/quickstart.md). This unified port eliminates cross-origin complications during local development and ensures the control plane behaves as it would in production.

### Embedded PostgreSQL with Zero Configuration

If `DATABASE_URL` is unset, the dev runner automatically provisions an embedded PostgreSQL instance. This removes external database dependencies for new contributors and guarantees version compatibility with Paperclip's schema expectations.

### File Watching and Auto-Restart Across the Monorepo

The runner monitors backend code, database migrations, UI components, and configuration files. As implemented in `scripts/dev-runner.ts#L5045-L5069`, it triggers safe restarts when changes are detected—preserving in-memory state where possible while ensuring code changes take effect immediately.

## Migration Handling and Schema Synchronization

Before the server accepts traffic, `pnpm dev` evaluates pending schema migrations. The logic in `scripts/dev-runner.ts#L4250-L4265` either prompts for confirmation or auto-applies migrations based on safety heuristics. This keeps the development database synchronized with `server/src/db/migrations` without requiring manual `prisma migrate` invocations.

## Plugin SDK Regeneration

On every restart, the dev runner rebuilds the plugin SDK as shown in `scripts/dev-runner.ts#L4778-L4892`. This ensures locally developed plugins compiled from `packages/plugin-sdk` are instantly available to running workspaces, eliminating the need for separate build watches.

## Service Registration and Local Discovery

The dev runtime registers itself with Paperclip's **local service supervisor**, implemented in [`server/src/services/local-service-supervisor.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/local-service-supervisor.ts). This registration—detailed in `scripts/dev-runner.ts#L1895-L1901` and `scripts/dev-runner.ts#L3320-L3329`—exposes:

- **URL**: The bound address for API/UI access
- **PID**: Process identifier for lifecycle management
- **Health status**: Current operational state

Other Paperclip components, such as workspace runtime controls in the UI, query this registry to discover and interact with the active dev environment.

## Network Binding Modes for Multi-Machine Testing

The dev runner supports configurable exposure beyond localhost. As defined in `scripts/dev-runner.ts#L58-L70` and utilized in `server/src/routes/access.ts#L1629-L1632`:

| Flag | Purpose |
|------|---------|
| `--bind lan` | Exposes the dev server to your local network for device testing |
| `--bind tailnet` | Publishes via Tailscale for secure remote collaboration |

These modes enable testing from mobile devices, browser stacks, or colleague machines without deployment pipelines.

## Common `pnpm dev` Commands and Variants

```bash

# Standard development mode with full watch and auto-restart

pnpm dev

```

```bash

# Single execution without file watching (CI scripts, debugging)

pnpm dev:once

```

```bash

# Expose to local network for cross-device testing

pnpm dev --bind lan

```

```bash

# Frontend-only mode when API runs separately

pnpm dev:ui

```

```bash

# Terminate running dev runtime and clean registry

pnpm dev:stop

```

These variants are defined in the root [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) script definitions and delegate to [`scripts/dev-runner.ts`](https://github.com/paperclipai/paperclip/blob/main/scripts/dev-runner.ts) with appropriate CLI flags.

## Key Implementation Files

| File | Responsibility |
|------|--------------|
| [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) | Entry point definitions for `dev`, `dev:once`, `dev:watch`, `dev:ui`, `dev:stop` |
| [`scripts/dev-runner.ts`](https://github.com/paperclipai/paperclip/blob/main/scripts/dev-runner.ts) | Core orchestration: environment setup, SDK build, file watching, migration handling, service registration, network binding |
| [`docs/start/quickstart.md`](https://github.com/paperclipai/paperclip/blob/main/docs/start/quickstart.md) | User-facing documentation confirming unified port 3100 and embedded database behavior |
| [`server/src/services/local-service-supervisor.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/local-service-supervisor.ts) | Persistent registry for dev runtime discovery |
| [`server/src/routes/access.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/access.ts) | Validation for `--bind` network modes |
| [`ui/src/pages/ProjectWorkspaceDetail.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/src/pages/ProjectWorkspaceDetail.tsx) | UI reference reinforcing `pnpm dev` as the expected startup command |

## Summary

- **`pnpm dev`** is the canonical command for Paperclip local development, unifying API, UI, and database in one terminal.
- It **auto-manages PostgreSQL**, **watches and restarts** on code changes, and **handles migrations** before server startup.
- The **plugin SDK rebuilds automatically** on every restart, keeping local plugin development friction-free.
- **Service registration** enables other Paperclip components to discover and control the dev runtime.
- **Network binding flags** (`--bind lan`, `--bind tailnet`) support realistic multi-device testing scenarios.

## Frequently Asked Questions

### What port does `pnpm dev` use by default?

Paperclip's dev server binds to **port 3100** for both API and UI traffic. This is hardcoded as the default in [`scripts/dev-runner.ts`](https://github.com/paperclipai/paperclip/blob/main/scripts/dev-runner.ts) and documented in [`docs/start/quickstart.md`](https://github.com/paperclipai/paperclip/blob/main/docs/start/quickstart.md). You can override this via `PORT` environment variable if needed.

### Does `pnpm dev` require a separate PostgreSQL installation?

No. When `DATABASE_URL` is unset, the dev runner automatically provisions an embedded PostgreSQL instance. This self-contained approach matches the zero-configuration philosophy described in the quickstart documentation.

### How does `pnpm dev` differ from `pnpm dev:once`?

`pnpm dev` enables **persistent file watching** and auto-restart behavior ideal for active development. `pnpm dev:once` executes a **single server run** without watchers—useful for CI pipelines, migration scripts, or debugging startup sequences without filesystem monitoring overhead.

### Can I run just the UI frontend with `pnpm dev`?

Yes. The `pnpm dev:ui` variant starts only the React development server, assuming you have the API running separately. This split mode is documented in the root [`package.json`](https://github.com/paperclipai/paperclip/blob/main/package.json) scripts and referenced in [`ui/src/pages/ProjectWorkspaceDetail.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/src/pages/ProjectWorkspaceDetail.tsx) for workspace control scenarios.