paperclipai onboard

Overview

The onboard command provides an interactive setup wizard that guides you through configuring your Paperclip instance for the first time. It configures database, LLM providers, logging, server settings, storage, and secrets management.

Syntax

paperclipai onboard [options]

Options

`--config <path>`

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

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

`--data-dir <path>`

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

paperclipai onboard --data-dir /custom/data

`--yes` / `-y`

Accept all defaults (quickstart mode). Skips all prompts and starts immediately.

paperclipai onboard -y

Behavior:

Uses Quickstart defaults
Skips setup mode selection
Automatically starts Paperclip after configuration

`--run`

Start Paperclip immediately after saving config.

paperclipai onboard --run

Setup Modes

When running without --yes, you’ll be prompted to choose a setup path:

Quickstart (Recommended)

Automatically configures:

Database: Embedded PostgreSQL on port 54329
Logging: File-based logs in ~/.paperclip/instances/<id>/logs
Server: Local trusted mode on 127.0.0.1:3100
Storage: Local disk in ~/.paperclip/instances/<id>/data/storage
Secrets: Local encrypted with auto-generated key
LLM: Not configured (can add later)

Advanced Setup

Provides interactive prompts for each configuration section:

Database - Choose between embedded PostgreSQL or managed Postgres
LLM Provider - Configure Claude or OpenAI (optional)
Logging - File-based or console logging
Server - Deployment mode, exposure, host, and port
Storage - Local disk or S3-compatible storage
Secrets - Encryption settings and key management

Interactive Workflow

1. Introduction

┌  paperclipai onboard
│
│  Local home: /home/user/.paperclip | instance: default | config: /home/user/.paperclip/instances/default/config.json
│

2. Setup Mode Selection

◆  Choose setup path
│  ○ Quickstart (Recommended: local defaults + ready to run)
│  ● Advanced setup (Customize database, server, storage, and more)
└

3. Configuration (Advanced mode)

Database Configuration

Prompts for database mode:

embedded-postgres - Built-in PostgreSQL (no external database needed)
postgres - Connect to external PostgreSQL instance

If selecting postgres, you’ll provide:

Connection string (e.g., postgres://user:pass@host:5432/dbname)
Connection is tested automatically

LLM Provider Configuration

Optional LLM configuration:

Provider: Claude or OpenAI
API Key: Your provider API key
Validation: Key is tested against provider API

◆  Configure LLM provider?
│  ● Yes
│  ○ No (skip)
│
◆  Select LLM provider
│  ● claude
│  ○ openai
│
◆  API key:
│  sk-ant-***************************
│
✓  API key is valid

Logging Configuration

Configure where logs are written:

Mode: file or console
Log directory: Path for file mode (default: ~/.paperclip/instances/default/logs)

Server Configuration

Server and auth settings: Deployment Mode:

local_trusted - No authentication, local development
authenticated - Full authentication required

Exposure:

private - Only allowed hostnames (authenticated mode)
public - Open access

Network:

Host: IP address to bind (default: 127.0.0.1)
Port: HTTP port (default: 3100)

Additional:

Serve UI: Whether to serve web UI from the server
Allowed hostnames: List of allowed client hostnames (authenticated/private only)

Storage Configuration

Configure where files are stored: Providers:

local_disk - Store files on local filesystem
s3 - Use S3 or S3-compatible storage

Local disk options:

Base directory: Path for file storage

S3 options:

Bucket: S3 bucket name
Region: AWS region
Endpoint: Custom endpoint (for S3-compatible services)
Prefix: Optional object key prefix
Force path style: Enable for non-AWS S3 providers

Secrets Configuration

Secrets encryption settings (uses local encrypted provider by default):

Provider: local_encrypted
Strict mode: Require secret refs for sensitive environment keys
Key file: Path to master encryption key (auto-generated)

4. Agent JWT Secret

A JWT secret is automatically generated or reused:

✔  Created PAPERCLIP_AGENT_JWT_SECRET in /home/user/.paperclip/instances/default/.env.local

This secret is required for local adapter authentication.

5. Secrets Key File

If using local encrypted secrets, a master key is generated:

✔  Created local secrets key file at /home/user/.paperclip/instances/default/secrets/master.key

Keep this key secure! It encrypts all secrets in your instance. Back it up safely.

6. Configuration Summary

┌  Configuration saved
│
│  Database: embedded-postgres
│  LLM: claude
│  Logging: file -> /home/user/.paperclip/instances/default/logs
│  Server: local_trusted/private @ 127.0.0.1:3100
│  Allowed hosts: (loopback only)
│  Auth URL mode: auto
│  Storage: local_disk
│  Secrets: local_encrypted (strict mode off)
│  Agent auth: PAPERCLIP_AGENT_JWT_SECRET configured
│

7. Next Steps

┌  Next commands
│
│  Run: paperclipai run
│  Reconfigure later: paperclipai configure
│  Diagnose setup: paperclipai doctor
│

8. Bootstrap CEO Invite (Authenticated mode only)

If you selected authenticated deployment mode, a bootstrap invite is generated:

▲  Generating bootstrap CEO invite
│
✔  Created bootstrap CEO invite.
│  Invite URL: http://localhost:3100/invite/pcp_bootstrap_***
│  Expires: 2026-03-07T22:30:00.000Z

Use this URL to create the first admin user.

9. Start Paperclip Prompt

Unless running with --yes or --run, you’ll be asked:

◆  Start Paperclip now?
│  ● Yes
│  ○ No
│

Selecting “Yes” runs paperclipai run automatically.

Examples

Quickstart with defaults

# Interactive quickstart
paperclipai onboard
# Select "Quickstart" when prompted

Fully automated setup

# Non-interactive, uses all defaults and starts immediately
paperclipai onboard --yes

Advanced configuration

# Interactive with full customization
paperclipai onboard
# Select "Advanced setup" when prompted

Custom config location

paperclipai onboard --config /etc/paperclip/production.json

Custom data directory

paperclipai onboard --data-dir /mnt/paperclip-data

Onboard and start immediately

paperclipai onboard --run

Configuration File

The onboard command creates a config.json file with this structure:

{
  "$meta": {
    "version": 1,
    "updatedAt": "2026-03-04T22:30:00.000Z",
    "source": "onboard"
  },
  "database": {
    "mode": "embedded-postgres",
    "embeddedPostgresDataDir": "/home/user/.paperclip/instances/default/db",
    "embeddedPostgresPort": 54329
  },
  "logging": {
    "mode": "file",
    "logDir": "/home/user/.paperclip/instances/default/logs"
  },
  "server": {
    "deploymentMode": "local_trusted",
    "exposure": "private",
    "host": "127.0.0.1",
    "port": 3100,
    "allowedHostnames": [],
    "serveUi": true
  },
  "auth": {
    "baseUrlMode": "auto"
  },
  "storage": {
    "provider": "local_disk",
    "localDisk": {
      "baseDir": "/home/user/.paperclip/instances/default/data/storage"
    }
  },
  "secrets": {
    "provider": "local_encrypted",
    "strictMode": false,
    "localEncrypted": {
      "keyFilePath": "/home/user/.paperclip/instances/default/secrets/master.key"
    }
  }
}

Updating Existing Configuration

If a config file already exists, onboard will update it:

│  /home/user/.paperclip/instances/default/config.json exists, updating config

Your choices will merge with or replace existing settings.

If the existing config is invalid, you’ll see a warning but can proceed to fix it.

Validation

Database Connection Test

When configuring external Postgres, the connection is tested:

◐  Testing database connection...
✔  Database connection successful

Or if it fails:

⚠  Could not connect to database — you can fix this later with `paperclipai doctor`

API Key Validation

LLM provider API keys are validated: Claude:

Tests against https://api.anthropic.com/v1/messages
Validates with a minimal request

OpenAI:

Tests against https://api.openai.com/v1/models
Validates authentication

Results:

✔  API key is valid

Or:

⚠  API key appears invalid — you can update it later
⚠  Could not reach API — continuing anyway

Troubleshooting

Port already in use

If the default port 3100 is occupied:

Choose a different port during advanced setup
Or change it later:
```
paperclipai configure --section server
```

Database connection fails

For external Postgres:

Verify connection string format:

postgres://username:password@host:port/database

Check network access and credentials
Run doctor to diagnose:
```
paperclipai doctor
```

Invalid API key

If LLM API key validation fails:

Double-check the key from your provider
Update later using:
```
paperclipai configure --section llm
```

Permission denied

If you can’t write to default paths:

Use a custom data directory:

paperclipai onboard --data-dir ~/my-paperclip

Or run with appropriate permissions

Next Steps

After onboarding:

Run Paperclip

Start your configured instance

Verify setup

Run diagnostic checks

Update config

Modify configuration sections

Commands

​Overview

​Syntax

​Options

​--config <path>

​--data-dir <path>

​--yes / -y

​--run

​Setup Modes

​Quickstart (Recommended)

​Advanced Setup

​Interactive Workflow

​1. Introduction

​2. Setup Mode Selection

​3. Configuration (Advanced mode)

​Database Configuration

​LLM Provider Configuration

​Logging Configuration

​Server Configuration

​Storage Configuration

​Secrets Configuration

​4. Agent JWT Secret

​5. Secrets Key File

​6. Configuration Summary

​7. Next Steps

​8. Bootstrap CEO Invite (Authenticated mode only)

​9. Start Paperclip Prompt

​Examples

​Quickstart with defaults

​Fully automated setup

​Advanced configuration

​Custom config location

​Custom data directory

​Onboard and start immediately

​Configuration File

​Updating Existing Configuration

​Validation

​Database Connection Test

​API Key Validation

​Troubleshooting

​Port already in use

​Database connection fails

​Invalid API key

​Permission denied

​Next Steps

Run Paperclip

Verify setup

Update config

Overview

Syntax

Options

`--config <path>`

`--data-dir <path>`

`--yes` / `-y`

`--run`

Setup Modes

Quickstart (Recommended)

Advanced Setup

Interactive Workflow

1. Introduction

2. Setup Mode Selection

3. Configuration (Advanced mode)

Database Configuration

LLM Provider Configuration

Logging Configuration

Server Configuration

Storage Configuration

Secrets Configuration

4. Agent JWT Secret

5. Secrets Key File

6. Configuration Summary

7. Next Steps

8. Bootstrap CEO Invite (Authenticated mode only)

9. Start Paperclip Prompt

Examples

Quickstart with defaults

Fully automated setup

Advanced configuration

Custom config location

Custom data directory

Onboard and start immediately

Configuration File

Updating Existing Configuration

Validation

Database Connection Test

API Key Validation

Troubleshooting

Port already in use

Database connection fails

Invalid API key

Permission denied

Next Steps