How to Install Paperclip AI: npx, Docker, Docker Compose & VPS (Step by Step)

Installing Paperclip AI takes about two minutes on a laptop and about twenty on a server. This guide covers every supported path: the one-line npx paperclipai onboard command, the verified install script, a Docker Compose deployment and a bare VPS. If you are still deciding whether the platform fits your business, start with our Paperclip AI guide and come back here when you are ready to run it. Everything below reflects the project as of September 2026 (release v2026.916.1).

Prerequisites

Paperclip is a Node.js server with a React dashboard and a PostgreSQL database. For a local install the database is embedded, so you do not need to install Postgres yourself. You do need:

Requirement	Version	Why
Node.js	24.11 or newer	The server and CLI run on Node. Older LTS releases fail on startup.
npm (bundled with Node)	Current	Runs the npx paperclipai command.
pnpm	9.15 or newer	Only needed if you clone the repo and run from source.
At least one model API key	Anthropic, OpenAI, OpenRouter or Gemini	Agents need a model. Subscription harnesses like Claude Code can also be used.
Disk and RAM	2 GB free disk, 4 GB RAM	Embedded Postgres, git worktrees and agent logs add up quickly.

Check your Node version before anything else:

node -v
# v24.11.0 or higher

If you are behind, install the current release from nodejs.org or use a version manager such as nvm install 24.

Method 1: Install with npx (fastest)

This is the path the Paperclip team recommends for a first install. It downloads the CLI, runs the onboarding wizard, provisions the embedded database and starts the server.

npx paperclipai onboard --yes

The --yes flag accepts sensible defaults so the wizard does not stop for questions. Drop it if you want to choose the install directory, port and model provider interactively. If you have registry mirrors configured and the package cannot be found, force the public registry:

npx --registry https://registry.npmjs.org paperclipai onboard --yes

When onboarding finishes, the API and dashboard are running at http://localhost:3100. Open that address in a browser and you will land on the empty company screen.

What onboarding asks

• Install location: where the CLI, config and embedded Postgres data live.
• Port: defaults to 3100. Change it only if something else already owns that port.
• Model provider and key: which provider your first agents should use. You can add more later under secrets.
• First company: a name and a one-line mission. Everything else, including agents and goals, is created in the dashboard.

Method 2: The official install script

The install script sets up a managed, persistent install with the paperclipai command on your PATH. The project publishes a checksum alongside the script, and you should verify it before running anything you pulled from the internet.

curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c install.sh.sha256
else
  shasum -a 256 -c install.sh.sha256
fi
bash install.sh

For servers, CI or anything scripted, run it non-interactively and onboard as a separate step:

curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
paperclipai onboard --yes

The script path is the one to use if you plan to keep the install around, because updates become a matter of re-running the script or the CLI update command rather than hunting for an npx cache.

Method 3: Test drive without installing

If you only want to see agents work before committing to anything, the test-drive command spins up an isolated, throwaway instance with a demo company already populated. Pass the key for whichever harness you want to try:

# Claude Code harness
ANTHROPIC_API_KEY=sk-ant-... npx paperclipai test-drive

# OpenAI Codex harness
OPENAI_API_KEY=sk-... npx paperclipai test-drive --harness codex

# OpenCode through OpenRouter, with a specific model
OPENROUTER_API_KEY=sk-or-... npx paperclipai test-drive --harness opencode --model openrouter/anthropic/claude-sonnet-4.5

Nothing from a test drive is meant to persist. Treat it as a demo, then do a real install with Method 1 or 2.

Method 4: Docker and Docker Compose

Docker is the right choice when you want Paperclip to survive reboots on a server, keep its database on a named volume and sit behind a reverse proxy. The moving parts are a Postgres container, the Paperclip server container and a volume for each. The official docs carry the current image name and environment variable list, and those change between releases, so treat the sketch below as a shape to adapt rather than something to paste blindly.

# docker-compose.yml - EXAMPLE SHAPE ONLY. Confirm image name,
# env var names and the current release tag in docs.paperclip.ing.
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: paperclip
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  paperclip:
    image: ghcr.io/paperclipai/paperclip:latest   # verify in docs
    depends_on:
      - db
    environment:
      DATABASE_URL: postgres://paperclip:change-me@db:5432/paperclip
      PORT: 3100
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    ports:
      - "127.0.0.1:3100:3100"
    volumes:
      - pcdata:/data
    restart: unless-stopped

volumes:
  pgdata:
  pcdata:

Three details matter more than the rest:

• Bind the port to localhost. The 127.0.0.1:3100:3100 mapping keeps the dashboard off the public internet. Put a reverse proxy with authentication in front of it, or reach it over a private network. Our hosting and self-hosting guide walks through both options.
• Use a real Postgres volume. Agents, tickets, budgets and the audit log all live in the database. Lose the volume and you lose the company.
• Keep API keys out of the compose file. Reference them from a .env file or your host's secret store.

Bring it up with docker compose up -d, then run the onboarding step inside the container or through the dashboard, depending on the image you are using.

Method 5: A VPS from scratch

On a fresh Ubuntu server the sequence is short. Create a non-root user, install Node 24, run the install script, and lock the port down.

# as root
adduser paperclip && usermod -aG sudo paperclip
su - paperclip

# install Node 24
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs build-essential

# install Paperclip
curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
paperclipai onboard --yes

Then either open the port only to a private network (Tailscale is the simplest option) or put Caddy or nginx in front with basic auth or an OAuth proxy. Several hosts, including Hostinger, Contabo and xCloud, now sell one-click Paperclip VPS templates that do most of this for you. They are convenient, but you should still understand what is running so you can update and back it up.

Your first company, agent and heartbeat

An install with no agents does nothing. Here is the shortest route to seeing work happen.

1. Create the company. Give it a name and a mission statement. Goals you add later will trace back to this line, and agents read it for context.
2. Add a goal. Something concrete such as "Publish a weekly summary of competitor pricing changes." Goals are what tickets get aligned to.
3. Hire an agent. Pick an adapter (Claude Code, Codex, OpenClaw, Hermes, OpenCode or a plain HTTP endpoint), give it a title and job description, and set a monthly budget. Paperclip pauses the agent automatically when it hits 100 percent of that budget, so start low.
4. Set a heartbeat. A heartbeat is a scheduled wake-up. Every interval, the agent checks its assigned tickets and picks up work. Ten minutes is a reasonable first value.
5. Create a ticket and assign it. Watch the activity log. You should see the agent check out the ticket, run tool calls and either finish or hand back with a question.

If you want to understand what is happening under the hood, the agent orchestration explainer covers org charts, heartbeats and budgets in depth. To wire your first agent to a specific runtime, see the guides for Claude Code and OpenClaw.

Windows notes

Paperclip is developed on macOS and Linux. On Windows, run it inside WSL2 with Ubuntu rather than native PowerShell. Install Node 24 inside the WSL distribution, then follow Method 1 or 2 exactly as written. The dashboard is still reachable from a Windows browser at localhost:3100 because WSL2 forwards ports automatically. Docker Desktop with the WSL2 backend also works for Method 4. Native Windows installs may run, but agent adapters that shell out to git or Unix tools tend to break.

Common errors and fixes

Symptom	Cause	Fix
Install fails with a syntax or engine error	Node older than 24.11	Upgrade Node, confirm with node -v, re-run.
EADDRINUSE or "port 3100 already in use"	Another process on the port, often a previous Paperclip instance	Find it with lsof -i :3100 and stop it, or set a different port during onboarding.
Dashboard loads but agents never run	No model key, or key stored under the wrong provider	Check the secrets page, confirm the agent's adapter matches the provider you funded.
Database connection refused (Docker)	Server started before Postgres was ready, or wrong DATABASE_URL	Add a healthcheck to the db service and confirm the URL host matches the service name.
Agent starts, then stops immediately	Budget set to zero or already at 100 percent	Raise the monthly budget on the agent page and resume it.
npx cannot find paperclipai	Private registry or stale cache	Use the --registry https://registry.npmjs.org flag shown above.

Frequently asked questions

Do I need to install PostgreSQL separately?

No. Local installs use an embedded Postgres instance that onboarding sets up for you. You only manage Postgres yourself in Docker or production deployments, where a dedicated database is the better choice anyway.

What is the default port for Paperclip AI?

The API and dashboard both listen on port 3100, so the local address is http://localhost:3100. You can choose another port during onboarding.

Can I install Paperclip AI on Windows?

Use WSL2 with Ubuntu. Install Node 24 inside WSL and follow the npx or install-script steps. Native Windows is not the supported path.

Does npx paperclipai onboard require an account?

No. Paperclip is MIT-licensed and self-hosted. There is no signup and no license key. You only need API keys for the model providers your agents will use.

How do I update Paperclip after installing?

Re-run the install script or the CLI update command, then restart the server. Read the release notes first, since some releases include database migrations. Our hosting guide covers safe update and rollback steps.

How much does it cost to run once installed?

The software is free. You pay for hosting and for model usage. See our Paperclip AI pricing breakdown for worked monthly numbers.