Local Deployment

Run Paperclip on your local machine for development and testing

Run Paperclip locally for development, testing, or single-operator workflows. Local deployment uses embedded PostgreSQL and requires no external dependencies.

Quick Start

The fastest way to get started:

npx paperclipai onboard --yes

Or clone and run manually:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

The server starts at http://localhost:3100 with an embedded PostgreSQL database.

Prerequisites

• Node.js 20+ - Required for running the server
• pnpm 9.15+ - Package manager (use corepack enable to install)

Default Local Setup

By default, local deployment runs in local_trusted mode:

• No login required - Optimized for fastest local startup
• Localhost-only binding - Binds to 127.0.0.1 for security
• Embedded database - PostgreSQL runs in-process
• Local file storage - Attachments stored on disk
• Company deletion enabled - Easy cleanup during development

Data Persistence

All data persists in ~/.paperclip/instances/default/:

~/.paperclip/instances/default/
├── db/                    # Embedded PostgreSQL data
├── data/storage/          # Uploaded files and attachments
├── secrets/master.key     # Local encryption key
├── workspaces/           # Agent workspace directories
└── config.json           # Instance configuration

Custom Data Directory

Override the default location:

PAPERCLIP_HOME=/custom/path pnpm paperclipai run

Multiple Instances

Run multiple isolated instances:

PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
PAPERCLIP_INSTANCE_ID=staging pnpm paperclipai run

Each instance gets its own directory under ~/.paperclip/instances/.

Development Commands

# Start development server with auto-reload
pnpm dev

# Run with full setup validation
pnpm paperclipai run

# Server only (no UI dev server)
pnpm dev:server

# Run tests
pnpm test:run

# Type checking
pnpm typecheck

# Build for production
pnpm build

Health Checks

Verify your local installation:

# Check server health
curl http://localhost:3100/api/health

# Expected: {"status":"ok"}

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

# Expected: JSON array

Reset Local Database

To wipe data and start fresh:

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

The database will be recreated automatically on next startup.

Docker Local Deployment

Run Paperclip in Docker without installing Node locally:

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

Or use Docker Compose:

docker compose -f docker-compose.quickstart.yml up --build

Data persists in the mounted volume (./data/docker-paperclip).

With AI Agent Support

To use local Claude or Codex adapters, pass API keys:

docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

Private Network Access (Tailscale)

For private network access while keeping authentication optional:

pnpm dev --tailscale-auth

This runs in authenticated/private mode and binds to 0.0.0.0.

Allow Custom Hostnames

Add private hostnames (e.g., Tailscale machine names):

pnpm paperclipai allowed-hostname my-macbook-pro

Troubleshooting

Port Already in Use

Change the default port:

PORT=3200 pnpm dev

Database Migration Issues

Run migrations manually:

pnpm db:migrate

Check Logs

Logs are written to .paperclip/logs/server.log:

tail -f .paperclip/logs/server.log

Next Steps

Configuration

Configure deployment mode, storage, and secrets

Database Setup

Switch to external PostgreSQL for production