Paperclip setup guide

How to install Paperclip on a VPS without getting lost

This page is written for first-time users, not just operators. The safest Paperclip VPS path is simple: prepare Node.js, use interactive onboarding, choose the right access mode, and validate the instance before you invite anyone else in.

Compare VPS plans Order Pro

What matters most

Use interactive onboarding for a real VPS

Paperclip's fast `--yes` quickstart uses local defaults. On a real VPS, interactive onboarding is safer because it lets you choose private or public access during setup.

Node.js 20+ is required

Paperclip's official docs list Node.js 20 or newer as the runtime baseline.

Install pnpm the simple way

For common users on a fresh VPS, installing `pnpm` with `npm install --global pnpm@latest-10` is easier than troubleshooting package-manager shims first.

You do not need a separate database first

Paperclip uses embedded PostgreSQL by default when `DATABASE_URL` is not set, which is ideal for a single VPS install.

Choose the right path

There are two setup styles, but only one is right for most VPS users

If this VPS will be used from a browser outside the server, the beginner-safe choice is the interactive onboarding flow. The fast `--yes` command is better kept for a short solo test.

Recommended for a real VPS

Interactive onboarding

This is the better choice when you need private or public access, want to make the right mode choice during setup, and do not want to redo the install later.

pnpm paperclipai onboard --run

During onboarding, choose the deployment mode that matches how the VPS will actually be used.

Only for a quick solo test

Fast local-default quickstart

This is fast, but it uses local defaults. It is fine for a throwaway test on the server, not the best first choice for a real cloud deployment.

npx paperclipai onboard --yes

Use this only when you want to see Paperclip running quickly and do not need proper private or public access yet.

Ubuntu 22.04 copy-paste

Use this block if your VPS is Ubuntu 22.04 and x64

This installs Node.js 22 LTS from the official Node.js download archive, installs `pnpm`, and gets the server ready for Paperclip onboarding. Most VPS servers are `x86_64`, but you can confirm with `uname -m` first.

Before you paste

If `uname -m` returns `aarch64` instead of `x86_64`, use the Linux ARM64 Node.js archive from nodejs.org instead of the Linux x64 archive shown below.

Commands

uname -m
sudo apt update
sudo apt install -y curl xz-utils

cd /tmp
curl -fsSLO https://nodejs.org/dist/v22.22.2/node-v22.22.2-linux-x64.tar.xz
sudo mkdir -p /usr/local/lib/nodejs
sudo tar -xJf node-v22.22.2-linux-x64.tar.xz -C /usr/local/lib/nodejs

echo 'export PATH=/usr/local/lib/nodejs/node-v22.22.2-linux-x64/bin:$PATH' >> ~/.profile
export PATH=/usr/local/lib/nodejs/node-v22.22.2-linux-x64/bin:$PATH

node -v
sudo npm install --global pnpm@latest-10
pnpm -v
pnpm paperclipai onboard --run

After onboarding, choose the deployment mode that matches the VPS: private for Tailscale or VPN access, public for an internet-facing install, or local only for a short test.

Step-by-step

Beginner install flow for a Paperclip VPS

This version is designed to keep common users moving: connect, prepare the runtime, onboard interactively, then verify the instance before real use.

1

Connect to the server and confirm it is the right machine

Start on a clean VPS with SSH access. You do not need to set up PostgreSQL first for a normal single-server install.

ssh user@your-server-ip
hostnamectl

2

Install Node.js 20+ and prepare pnpm

Paperclip needs Node.js 20 or newer. After Node.js is installed, install `pnpm` and confirm both tools are available before you continue.

node -v
sudo npm install --global pnpm@latest-10
pnpm -v

If `node -v` shows anything below 20, stop here and upgrade Node.js before continuing.

3

Run interactive onboarding and choose the right mode

This is the safest first install on a VPS because you make the important network and login decisions during setup instead of accepting local defaults.

pnpm paperclipai onboard --run

Choose Quickstart

Only if this is a short local-style test on the VPS.

Choose Advanced setup

Use this for a normal private or public VPS install.

4

Verify the service before you open it in a browser

Check the local health endpoint on the server first. Once it responds, open the private or public URL that matches the mode you selected during onboarding.

curl http://localhost:3100/api/health

Paperclip's official docs show port `3100` as the default server port.

The simple beginner rule is this: use `pnpm paperclipai onboard --run` for a real VPS install, and keep `npx paperclipai onboard --yes` for a short local-default test only.

Deployment modes

Choose the mode based on how people will reach Paperclip.

This one choice affects login, networking, and whether the instance is ready for real VPS use.

`local_trusted`

Best for solo learning and isolated testing. It is loopback-only and does not give you the normal private or public access most VPS users expect.

Authenticated + private

Best when the VPS is only reachable through Tailscale, VPN, or LAN. This is often the easiest safe choice for teams that do not want a public URL yet.

Authenticated + public

Best for a normal cloud deployment with an internet-facing URL. This is the mode most visitors should expect if they are buying a VPS specifically for Paperclip hosting.

After the install

What common users should do first inside Paperclip

The official quickstart flow after installation is not complicated. Open the app, create the company, define the goal, then add your first agents.

1. Create the first company

This becomes the top-level workspace for goals, agents, budgets, and issues.

2. Write one clear company goal

Start with a real objective so the first agents have direction and context.

3. Create a CEO agent and choose its adapter

This is the first working agent and the base for the rest of the org chart.

4. Add more roles only after the first agent is working

That keeps the first setup manageable and reduces confusion on a new VPS install.

What Paperclip creates for you

You do not need to build every piece by hand

Paperclip's official docs describe a default instance layout under `~/.paperclip/instances/default/`. This makes it easier to understand where the app stores config, logs, data, and secrets on the VPS.

~/.paperclip/instances/default/config.json
~/.paperclip/instances/default/db
~/.paperclip/instances/default/logs
~/.paperclip/instances/default/data/storage
~/.paperclip/instances/default/secrets/master.key

Embedded PostgreSQL

Used by default when you do not provide `DATABASE_URL`.

Secrets key

Created locally so sensitive values can be encrypted on the instance.

Logs and storage

Stored inside the instance directory so you know where to look and what to back up.

Good for beginners

A single VPS can run Paperclip cleanly without adding a separate database on day one.

Troubleshooting

Common setup problems and the official command that helps

This section is intentionally practical. Start with health, then doctor, then fix the server section if the mode or URL is wrong.

Useful commands

curl http://localhost:3100/api/health
pnpm paperclipai doctor
pnpm paperclipai doctor --repair
pnpm paperclipai configure --section server
pnpm paperclipai allowed-hostname my-machine

Use `doctor` when the environment looks wrong, `configure --section server` when the mode or URL is wrong, and `allowed-hostname` when a private-network hostname needs to be trusted.

The app starts, but you cannot reach it from your browser

That is usually a mode or URL problem, not a full install failure. Revisit the server section first.

You used `--yes`, but now need a real VPS setup

Move to the interactive flow so you can choose authenticated private or authenticated public instead of staying on local defaults.

Private network access works for some hosts but not others

Use the hostname allow-list command from the official deployment-mode docs when a Tailscale or private hostname needs to be added.

Next step

Choose the VPS, then install Paperclip the beginner-safe way

If you want the shortest accurate answer, start with Pro, prepare Node.js 20+, use interactive onboarding, and choose the mode that matches how the VPS will actually be used.

Compare plans Order Pro Open docs