Installation

Install Paperclip using npx, manual setup, or Docker

Overview

Paperclip can be installed in three ways:

1. NPX Onboard (Recommended) — Fastest path, includes interactive setup
2. Manual Git Clone — For contributors and advanced customization
3. Docker — Containerized deployment without Node/pnpm locally

All methods support both local development (embedded PostgreSQL) and production deployment (external PostgreSQL).

Prerequisites

Choose the prerequisites based on your installation method:

NPX

• Node.js 20+ (download)
• pnpm 9.15+ — Install with npm install -g pnpm

Manual

• Node.js 20+ (download)
• pnpm 9.15+ — Install with npm install -g pnpm
• Git (download)

Docker

• Docker (download)
• No Node.js or pnpm required!

Method 1: NPX Onboard (Recommended)

The fastest way to get started. This method downloads the CLI and runs an interactive setup wizard.

Quickstart Mode

Accept all defaults and start immediately:

npx paperclipai onboard --yes

This creates:

• Config at ~/.paperclip/instances/default/config.json
• Embedded PostgreSQL database at ~/.paperclip/instances/default/db
• Local file storage at ~/.paperclip/instances/default/data/storage
• Server running at http://localhost:3100

Interactive Mode

Customize database, server, and storage settings:

npx paperclipai onboard

You’ll be prompted to choose:

1. Setup Path

   • Quickstart: Local defaults, ready to run
   • Advanced: Customize all settings
2. Database

   • Embedded PostgreSQL (default, no setup required)
   • External PostgreSQL (provide connection string)
3. LLM Provider

   Optional: Configure default LLM for agents

   • Claude (Anthropic)
   • OpenAI
   • Local model
4. Server Settings

   • Host: 127.0.0.1 (local) or 0.0.0.0 (network-accessible)
   • Port: Default 3100
   • Deployment Mode: local_trusted or authenticated
5. Storage

   • Local Disk (default)
   • S3-compatible (for production)

Start the Server

After onboarding:

paperclipai run

Or start manually with custom config:

paperclipai run --config /path/to/config.json

Run paperclipai doctor anytime to diagnose issues with your setup.

Method 2: Manual Git Clone

For contributors or advanced users who want full control over the source code.

Clone the Repository

git clone https://github.com/paperclipai/paperclip.git
cd paperclip

Install Dependencies

pnpm install

Make sure you’re using pnpm 9.15+. Using npm or yarn will not work with this monorepo.

Start Development Server

Run the full stack (API + UI) in development mode:

pnpm dev

This starts:

• API server: http://localhost:3100/api
• UI: http://localhost:3100 (served by API server in dev mode)
• Embedded PostgreSQL: Auto-created at data/pglite/

Development Commands

Full Stack

pnpm dev

Database Management

Generate a new migration after schema changes:

pnpm db:generate

Apply migrations manually:

pnpm db:migrate

By default, migrations run automatically on server start. Set PAPERCLIP_MIGRATION_PROMPT=never to disable prompts.

Reset Local Database

Delete the embedded database and start fresh:

rm -rf data/pglite
pnpm dev

Method 3: Docker

Run Paperclip in a container without installing Node.js or pnpm locally.

One-Liner (Build + Run)

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

Open http://localhost:3100 to access the UI.

Docker Compose

Use the quickstart compose file:

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

Defaults:

• Host port: 3100
• Data directory: ./data/docker-paperclip

Custom port and data directory:

PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
  docker compose -f docker-compose.quickstart.yml up --build

Data Persistence

All data persists in the bind mount volume:

• Embedded PostgreSQL database
• Uploaded assets
• Local secrets encryption key
• Agent workspace data

If you remove the volume, all data is lost. Make sure to back up ./data/docker-paperclip if needed.

Using Claude/Codex Adapters in Docker

The Docker image pre-installs:

• claude (Anthropic Claude Code CLI)
• codex (OpenAI Codex CLI)

To enable these adapters, pass API keys when starting the container:

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

Without API keys, the app runs normally. Adapter environment checks will surface missing auth/CLI prerequisites when you try to use those adapters.

Configuration

After installation, customize your Paperclip instance:

View Current Config

paperclipai env

This prints all environment variables derived from your config file.

Update Configuration

Reconfigure specific sections:

paperclipai configure --section database
paperclipai configure --section server
paperclipai configure --section storage

Config File Location

By default, configs are stored at:

~/.paperclip/instances/default/config.json

Override with:

paperclipai run --config /custom/path/config.json

Or use a custom instance ID:

paperclipai run --instance production
# Uses: ~/.paperclip/instances/production/config.json

Environment Variables

You can override config with environment variables:

Server

HOST=0.0.0.0
PORT=3100
PAPERCLIP_HOME=~/.paperclip/instances/default

See Environment Variables for the complete list.

Deployment Modes

Paperclip supports two deployment modes:

Local Trusted (Default)

Single-user local deployment with no login friction.

{
  "server": {
    "deploymentMode": "local_trusted",
    "exposure": "private",
    "host": "127.0.0.1",
    "port": 3100
  }
}

Use when:

• Running on your local machine
• Accessed only by you
• No authentication needed

Authenticated

Login-required mode for private-network or public deployments.

{
  "server": {
    "deploymentMode": "authenticated",
    "exposure": "public",
    "host": "0.0.0.0",
    "port": 3100
  },
  "auth": {
    "baseUrlMode": "explicit",
    "baseUrl": "https://paperclip.mycompany.com"
  }
}

Use when:

• Deploying to a server
• Multiple users need access
• Exposing on public internet

See Deployment Modes for details.

Next Steps

Quickstart

Create your first company and hire agents

Database Setup

Configure external PostgreSQL for production

Secrets Management

Set up secure secret storage

Agent Adapters

Connect OpenClaw, Claude, or custom agents

Troubleshooting

pnpm: command not found

Install pnpm globally:

npm install -g pnpm

Verify installation:

pnpm --version

Node version too old

Paperclip requires Node.js 20 or higher.

Check your version:

node --version

Upgrade Node.js:

• Download from nodejs.org
• Or use nvm:
  nvm install 20
  nvm use 20
  

Port 3100 already in use

Change the port:

PORT=3200 paperclipai run

Or update your config:

paperclipai configure --section server

Database migration failed

Reset migrations:

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

Or run migrations manually:

pnpm db:migrate

Docker container won't start

Check logs:

docker logs paperclip

Ensure the data directory exists and has write permissions:

mkdir -p ./data/docker-paperclip
chmod 755 ./data/docker-paperclip

Getting Help

Run Diagnostics

paperclipai doctor --repair

Discord Community

Ask questions and get support

GitHub Issues

Report bugs and request features

Documentation

Browse the full docs