paperclipai run - Paperclip

Overview

The run command is the primary way to start your Paperclip instance. It automatically handles onboarding (if needed), runs diagnostic checks, and starts the server. This is the command you’ll use most often in development and production.

Syntax

paperclipai run [options]

Options

`--config <path>`

Path to config file. Default: ~/.paperclip/instances/default/config.json

paperclipai run --config /etc/paperclip/config.json

`--data-dir <path>`

Paperclip data directory root. Isolates state from ~/.paperclip.

paperclipai run --data-dir /custom/data

`--instance <id>`

Local instance ID. Useful for running multiple isolated instances. Default: default Allowed characters: Letters, numbers, _, and -

paperclipai run --instance production

`--repair`

Attempt automatic repairs during doctor checks. Default: true

paperclipai run --repair

`--no-repair`

Disable automatic repairs during doctor checks.

paperclipai run --no-repair

What It Does

The run command executes a three-phase startup sequence:

1. Setup Validation

Checks for existing configuration:

┌  paperclipai run
│
│  Home: /home/user/.paperclip
│  Instance: default
│  Config: /home/user/.paperclip/instances/default/config.json
│

Creates home directory if missing
Creates instance directory if missing
Checks for config file

2. Auto-Onboarding

If no config is found: Interactive terminal:

▲  No config found. Starting onboarding...

Runs paperclipai onboard automatically, then continues. Non-interactive terminal (CI/automated):

✖  No config found and terminal is non-interactive.
│  Run paperclipai onboard once, then retry paperclipai run.

Exits with code 1.

3. Health Checks

Runs paperclipai doctor with automatic repairs:

▲  Running doctor checks...
│
✓ Config file: Valid config at /home/user/.paperclip/instances/default/config.json
✓ Deployment/auth mode: local_trusted mode (no authentication required)
✓ Agent JWT secret: PAPERCLIP_AGENT_JWT_SECRET configured
✓ Secrets adapter: Local encrypted secrets configured
✓ Storage adapter: Local disk storage configured at /home/user/.paperclip/instances/default/data/storage
✓ Database: Embedded Postgres will start on port 54329
✓ LLM provider: Claude configured (API key present)
✓ Log directory: /home/user/.paperclip/instances/default/logs
✓ Server port: Port 3100 is available
│
┌  Summary
│  9 passed
│

If any checks fail and can’t be auto-repaired:

✖  Doctor found blocking issues. Not starting server.

Exits with code 1.

4. Server Start

If all checks pass:

▲  Starting Paperclip server...

The server process takes over and outputs:

🔌 Paperclip API listening on http://127.0.0.1:3100
🌐 UI available at http://127.0.0.1:3100
📊 Database: embedded-postgres (port 54329)
✨ Ready for requests

The server runs in the foreground. Press Ctrl+C to stop.

Examples

Start default instance

paperclipai run

Starts with defaults:

Instance: default
Config: ~/.paperclip/instances/default/config.json
Auto-repair: enabled

Start specific instance

paperclipai run --instance staging

Uses configuration from ~/.paperclip/instances/staging/config.json.

Custom config path

paperclipai run --config /etc/paperclip/prod.json

Overrides default config location.

Disable auto-repair

paperclipai run --no-repair

Doctor will only report issues without attempting fixes.

Multiple instances

Run multiple instances simultaneously:

# Terminal 1: Development
PAPERCLIP_INSTANCE_ID=dev paperclipai run

# Terminal 2: Staging
PAPERCLIP_INSTANCE_ID=staging paperclipai run

Each instance needs:

Unique instance ID
Unique port (configure in config.json)
Separate database (if using embedded-postgres)

Environment Variables

These environment variables affect run behavior:

`PAPERCLIP_INSTANCE_ID`

Sets the instance ID.

PAPERCLIP_INSTANCE_ID=production paperclipai run

`PAPERCLIP_CONFIG`

Explicit config file path.

PAPERCLIP_CONFIG=/etc/paperclip/config.json paperclipai run

`PAPERCLIP_HOME`

Override home directory.

PAPERCLIP_HOME=/opt/paperclip paperclipai run

`PAPERCLIP_OPEN_ON_LISTEN`

Auto-open browser when server starts (set internally by onboard).

PAPERCLIP_OPEN_ON_LISTEN=true paperclipai run

`PAPERCLIP_UI_DEV_MIDDLEWARE`

Enable UI development middleware (auto-detected in monorepo).

PAPERCLIP_UI_DEV_MIDDLEWARE=true paperclipai run

Server Modes

Development Mode

If running from the monorepo workspace:

cd /path/to/paperclip-monorepo
paperclipai run

Behavior:

Imports server/src/index.ts directly
Enables UI dev middleware
Supports hot reloading (with tsx/nodemon)

Production Mode

If installed globally or using published package:

paperclipai run

Behavior:

Imports @paperclipai/server package
Serves pre-built UI assets
Production-optimized

Server Output

Successful Start

Paperclip v0.2.5
🔌 Paperclip API listening on http://127.0.0.1:3100
🌐 UI available at http://127.0.0.1:3100
📊 Database: embedded-postgres (port 54329)
📝 Logs: /home/user/.paperclip/instances/default/logs
💾 Storage: local_disk (/home/user/.paperclip/instances/default/data/storage)
🔐 Mode: local_trusted
✨ Ready for requests

Request Logs

HTTP requests are logged:

GET /api/companies 200 12ms
POST /api/agents 201 45ms
GET /api/heartbeat-runs/abc123/events 200 8ms

Database Migrations

On first start or schema changes:

📊 Running database migrations...
✓ Applied 3 migrations

Stopping the Server

Graceful Shutdown

Press Ctrl+C to trigger graceful shutdown:

^C
⏸  Shutting down gracefully...
✓ Closed database connections
✓ Stopped heartbeat scheduler
✓ Server stopped

Force Kill

If graceful shutdown hangs, press Ctrl+C again:

^C^C
✖ Force stopping server

Troubleshooting

Port already in use

Error: listen EADDRINUSE: address already in use 127.0.0.1:3100

Solutions:

Check what’s using the port:

lsof -i :3100
# or
netstat -tuln | grep 3100

Kill the conflicting process:
kill <PID>

Change the port:

paperclipai configure --section server
# Select a different port

Database connection failed

✖ Database: Connection failed

For embedded-postgres:

Check logs:

tail -f ~/.paperclip/instances/default/logs/server.log

Verify port is available:
lsof -i :54329

Reset database:

# Stop server
# Remove DB directory
rm -rf ~/.paperclip/instances/default/db
# Restart
paperclipai run

For external postgres:

Test connection manually:

psql "postgres://user:pass@host:5432/dbname"

Verify DATABASE_URL:
paperclipai env | grep DATABASE_URL

Update connection:

paperclipai configure --section database

Server starts but UI not accessible

Check server config:

paperclipai env | grep PORT

Verify UI is enabled: In config.json:

{
  "server": {
    "serveUi": true
  }
}

Try different host: If bound to 127.0.0.1, only accessible locally. For network access:

paperclipai configure --section server
# Set host to 0.0.0.0

Security: Only bind to 0.0.0.0 in trusted networks or with proper authentication.

Module not found error

Error: Could not locate a Paperclip server entrypoint.
Tried: /path/to/server/src/index.ts, @paperclipai/server

Solutions:

Reinstall dependencies:
npm install -g paperclipai
Verify installation:
npm list -g @paperclipai/server
Use npx instead:
npx paperclipai run

Doctor fails with blocking issues

✖ Doctor found blocking issues. Not starting server.

Run doctor separately to see details:

paperclipai doctor --repair

Fix issues manually and retry:

paperclipai run

Production Deployment

For production deployments:

Using systemd

Create /etc/systemd/system/paperclip.service:

[Unit]
Description=Paperclip AI Control Plane
After=network.target

[Service]
Type=simple
User=paperclip
WorkingDirectory=/opt/paperclip
Environment="PAPERCLIP_CONFIG=/etc/paperclip/config.json"
Environment="NODE_ENV=production"
ExecStart=/usr/bin/paperclipai run --no-repair
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable paperclip
sudo systemctl start paperclip
sudo systemctl status paperclip

Using Docker

Create Dockerfile:

FROM node:20-alpine

RUN npm install -g paperclipai

WORKDIR /app
COPY config.json /app/config.json

EXPOSE 3100

CMD ["paperclipai", "run", "--config", "/app/config.json"]

Build and run:

docker build -t paperclip .
docker run -p 3100:3100 -v paperclip-data:/data paperclip

Environment Variables for Production

Set these in production:

export DATABASE_URL="postgres://user:pass@db-host:5432/paperclip"
export PAPERCLIP_AGENT_JWT_SECRET="<secure-secret>"
export PAPERCLIP_CONFIG="/etc/paperclip/config.json"
export NODE_ENV="production"
export PORT="3100"

Generate export block:

paperclipai env

Next Steps

Verify health

Run diagnostic checks on your running instance

Update config

Modify configuration without stopping

Production setup

Deploy to production environments

​Overview

​Syntax

​Options

​--config <path>

​--data-dir <path>

​--instance <id>

​--repair

​--no-repair

​What It Does

​1. Setup Validation

​2. Auto-Onboarding

​3. Health Checks

​4. Server Start

​Examples

​Start default instance

​Start specific instance

​Custom config path

​Disable auto-repair

​Multiple instances

​Environment Variables

​PAPERCLIP_INSTANCE_ID

​PAPERCLIP_CONFIG

​PAPERCLIP_HOME

​PAPERCLIP_OPEN_ON_LISTEN

​PAPERCLIP_UI_DEV_MIDDLEWARE

​Server Modes

​Development Mode

​Production Mode

​Server Output

​Successful Start

​Request Logs

​Database Migrations

​Stopping the Server

​Graceful Shutdown

​Force Kill

​Troubleshooting

​Port already in use

​Database connection failed

​Server starts but UI not accessible

​Module not found error

​Doctor fails with blocking issues

​Production Deployment

​Using systemd

​Using Docker

​Environment Variables for Production

​Next Steps

Verify health

Update config

Production setup

Overview

Syntax

Options

`--config <path>`

`--data-dir <path>`

`--instance <id>`

`--repair`

`--no-repair`

What It Does

1. Setup Validation

2. Auto-Onboarding

3. Health Checks

4. Server Start

Examples

Start default instance

Start specific instance

Custom config path

Disable auto-repair

Multiple instances

Environment Variables

`PAPERCLIP_INSTANCE_ID`

`PAPERCLIP_CONFIG`

`PAPERCLIP_HOME`

`PAPERCLIP_OPEN_ON_LISTEN`

`PAPERCLIP_UI_DEV_MIDDLEWARE`

Server Modes

Development Mode

Production Mode

Server Output

Successful Start

Request Logs

Database Migrations

Stopping the Server

Graceful Shutdown

Force Kill

Troubleshooting

Port already in use

Database connection failed

Server starts but UI not accessible

Module not found error

Doctor fails with blocking issues

Production Deployment

Using systemd

Using Docker

Environment Variables for Production

Next Steps