> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/paperclipai/paperclip/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  All methods support both local development (embedded PostgreSQL) and production deployment (external PostgreSQL).
</Note>

## Prerequisites

Choose the prerequisites based on your installation method:

<Tabs>
  <Tab title="NPX">
    * **Node.js 20+** ([download](https://nodejs.org/))
    * **pnpm 9.15+** — Install with `npm install -g pnpm`
  </Tab>

  <Tab title="Manual">
    * **Node.js 20+** ([download](https://nodejs.org/))
    * **pnpm 9.15+** — Install with `npm install -g pnpm`
    * **Git** ([download](https://git-scm.com/))
  </Tab>

  <Tab title="Docker">
    * **Docker** ([download](https://www.docker.com/products/docker-desktop/))
    * No Node.js or pnpm required!
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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:

```bash theme={null}
npx paperclipai onboard
```

You'll be prompted to choose:

<Steps>
  <Step title="Setup Path">
    * **Quickstart**: Local defaults, ready to run
    * **Advanced**: Customize all settings
  </Step>

  <Step title="Database" skip={"if Quickstart"}>
    * **Embedded PostgreSQL** (default, no setup required)
    * **External PostgreSQL** (provide connection string)
  </Step>

  <Step title="LLM Provider" skip={"if Quickstart"}>
    Optional: Configure default LLM for agents

    * Claude (Anthropic)
    * OpenAI
    * Local model
  </Step>

  <Step title="Server Settings" skip={"if Quickstart"}>
    * **Host**: `127.0.0.1` (local) or `0.0.0.0` (network-accessible)
    * **Port**: Default `3100`
    * **Deployment Mode**: `local_trusted` or `authenticated`
  </Step>

  <Step title="Storage" skip={"if Quickstart"}>
    * **Local Disk** (default)
    * **S3-compatible** (for production)
  </Step>
</Steps>

### Start the Server

After onboarding:

```bash theme={null}
paperclipai run
```

Or start manually with custom config:

```bash theme={null}
paperclipai run --config /path/to/config.json
```

<Tip>
  Run `paperclipai doctor` anytime to diagnose issues with your setup.
</Tip>

## Method 2: Manual Git Clone

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

### Clone the Repository

```bash theme={null}
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
```

### Install Dependencies

```bash theme={null}
pnpm install
```

<Warning>
  Make sure you're using **pnpm 9.15+**. Using npm or yarn will not work with this monorepo.
</Warning>

### Start Development Server

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

```bash theme={null}
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

<CodeGroup>
  ```bash Full Stack theme={null}
  pnpm dev
  ```

  ```bash Server Only theme={null}
  pnpm dev:server
  ```

  ```bash UI Only theme={null}
  pnpm dev:ui
  ```

  ```bash Type Checking theme={null}
  pnpm typecheck
  ```

  ```bash Run Tests theme={null}
  pnpm test:run
  ```

  ```bash Build for Production theme={null}
  pnpm build
  ```
</CodeGroup>

### Database Management

Generate a new migration after schema changes:

```bash theme={null}
pnpm db:generate
```

Apply migrations manually:

```bash theme={null}
pnpm db:migrate
```

<Info>
  By default, migrations run automatically on server start. Set `PAPERCLIP_MIGRATION_PROMPT=never` to disable prompts.
</Info>

### Reset Local Database

Delete the embedded database and start fresh:

```bash theme={null}
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)

```bash theme={null}
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](http://localhost:3100)** to access the UI.

### Docker Compose

Use the quickstart compose file:

```bash theme={null}
docker compose -f docker-compose.quickstart.yml up --build
```

**Defaults:**

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

**Custom port and data directory:**

```bash theme={null}
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

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

### 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:

```bash theme={null}
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
```

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

## Configuration

After installation, customize your Paperclip instance:

### View Current Config

```bash theme={null}
paperclipai env
```

This prints all environment variables derived from your config file.

### Update Configuration

Reconfigure specific sections:

```bash theme={null}
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:

```bash theme={null}
paperclipai run --config /custom/path/config.json
```

Or use a custom instance ID:

```bash theme={null}
paperclipai run --instance production
# Uses: ~/.paperclip/instances/production/config.json
```

## Environment Variables

You can override config with environment variables:

<CodeGroup>
  ```bash Server theme={null}
  HOST=0.0.0.0
  PORT=3100
  PAPERCLIP_HOME=~/.paperclip/instances/default
  ```

  ```bash Database theme={null}
  DATABASE_URL=postgresql://user:pass@localhost:5432/paperclip
  ```

  ```bash Storage theme={null}
  STORAGE_PROVIDER=s3
  S3_BUCKET=my-paperclip-assets
  S3_REGION=us-east-1
  AWS_ACCESS_KEY_ID=...
  AWS_SECRET_ACCESS_KEY=...
  ```

  ```bash Auth theme={null}
  DEPLOYMENT_MODE=authenticated
  BASE_URL=https://paperclip.mycompany.com
  ```
</CodeGroup>

See [Environment Variables](/deployment/configuration) for the complete list.

## Deployment Modes

Paperclip supports two deployment modes:

### Local Trusted (Default)

Single-user local deployment with no login friction.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/deployment/configuration) for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first company and hire agents
  </Card>

  <Card title="Database Setup" icon="database" href="/deployment/database">
    Configure external PostgreSQL for production
  </Card>

  <Card title="Secrets Management" icon="key" href="/deployment/security">
    Set up secure secret storage
  </Card>

  <Card title="Agent Adapters" icon="plug" href="/agents/overview">
    Connect OpenClaw, Claude, or custom agents
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="pnpm: command not found">
    Install pnpm globally:

    ```bash theme={null}
    npm install -g pnpm
    ```

    Verify installation:

    ```bash theme={null}
    pnpm --version
    ```
  </Accordion>

  <Accordion title="Node version too old">
    Paperclip requires Node.js 20 or higher.

    Check your version:

    ```bash theme={null}
    node --version
    ```

    Upgrade Node.js:

    * Download from [nodejs.org](https://nodejs.org/)
    * Or use [nvm](https://github.com/nvm-sh/nvm):
      ```bash theme={null}
      nvm install 20
      nvm use 20
      ```
  </Accordion>

  <Accordion title="Port 3100 already in use">
    Change the port:

    ```bash theme={null}
    PORT=3200 paperclipai run
    ```

    Or update your config:

    ```bash theme={null}
    paperclipai configure --section server
    ```
  </Accordion>

  <Accordion title="Database migration failed">
    Reset migrations:

    ```bash theme={null}
    rm -rf ~/.paperclip/instances/default/db
    paperclipai run
    ```

    Or run migrations manually:

    ```bash theme={null}
    pnpm db:migrate
    ```
  </Accordion>

  <Accordion title="Docker container won't start">
    Check logs:

    ```bash theme={null}
    docker logs paperclip
    ```

    Ensure the data directory exists and has write permissions:

    ```bash theme={null}
    mkdir -p ./data/docker-paperclip
    chmod 755 ./data/docker-paperclip
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

<CardGroup cols={2}>
  <Card title="Run Diagnostics" icon="stethoscope">
    ```bash theme={null}
    paperclipai doctor --repair
    ```
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/m4HZY7xNG3">
    Ask questions and get support
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/paperclipai/paperclip/issues">
    Report bugs and request features
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the full docs
  </Card>
</CardGroup>