PA
Paperclip AI

Paperclip docs

Paperclip docs for people setting up a VPS for the first time

This page is the simple reference version of the setup guide. Use it when you want the shortest safe install path, the commands you will actually reuse, the meaning of each deployment mode, and the fastest fixes when something feels off.

Open setup guide Ubuntu 22.04 commands

Quick answers

Safest first command for a real VPS

Use `pnpm paperclipai onboard --run`, not the fast `--yes` quickstart, if the server will be used in private or public mode.

Default server port

Paperclip serves on port `3100` by default, so `curl http://localhost:3100/api/health` is the fastest first check.

Database requirement

You do not need to bring PostgreSQL on day one. Paperclip uses embedded PostgreSQL automatically when `DATABASE_URL` is not set.

Need exact Ubuntu commands?

Use the copy-paste Ubuntu 22.04 block in the setup guide if you want the runtime install commands without extra guesswork.

Safe Path Commands Modes Files First Login Fixes

Safe Path

The shortest accurate path for a normal Paperclip VPS install

Use this when the goal is a real VPS deployment, not a disposable test. It keeps the install simple while still leaving room for private or public access.

  • Start with a clean Ubuntu 22.04 VPS and install Node.js 20 or newer.
  • Install `pnpm`, then run `pnpm paperclipai onboard --run` so you can choose the correct deployment mode during setup.
  • Check `http://localhost:3100/api/health` first, then open the private or public URL that matches the selected mode. 
node -v
sudo npm install --global pnpm@latest-10
pnpm paperclipai onboard --run
curl http://localhost:3100/api/health

If you need the full Ubuntu 22.04 runtime install block, use the dedicated section in the setup guide. That block is written specifically for common VPS users.

Commands

Commands you will actually reuse

These are the Paperclip commands that matter most on a VPS. The goal here is usefulness, not completeness.

First-time install

pnpm paperclipai onboard --run

Best first command for a real VPS because it lets you choose the mode during setup.

Fast local-default test

npx paperclipai onboard --yes

Use only when you intentionally want a quick solo test with local defaults.

Start or restart the app

pnpm paperclipai run

Use this after onboarding when you want Paperclip to start cleanly and recheck the environment.

Check the environment

pnpm paperclipai doctor
pnpm paperclipai doctor --repair

Use `doctor` when the install feels wrong or the server settings need to be repaired.

Change the server mode later

pnpm paperclipai configure --section server

Use this if you installed first and later realized the VPS needs private or public access instead.

Trust a private-network hostname

pnpm paperclipai allowed-hostname my-machine

Useful when you are using Tailscale or another private hostname and need Paperclip to trust it.

Modes

Choose the deployment mode based on how people will reach the server

Most setup mistakes happen because the mode does not match the real access pattern. The easier rule is to decide this before you finish onboarding.

`local_trusted`

Use this for solo learning and isolated testing. It binds locally and is not the normal choice for a VPS you want to open from another machine.

Authenticated + private

Use this for Tailscale, VPN, or LAN access. It is often the best first production-like choice because it stays off the public internet.

Authenticated + public

Use this when the VPS will have a public URL. This mode needs the cleanest server setup because it is the normal internet-facing deployment path.

Files

Where Paperclip stores things on the VPS

Paperclip creates a predictable default instance directory under `~/.paperclip/instances/default/`. This is useful when you need to inspect the install, back it up, or understand what changed.

Config

~/.paperclip/instances/default/config.json

Main instance configuration created during onboarding.

Database

~/.paperclip/instances/default/db

Embedded PostgreSQL data when `DATABASE_URL` is not set.

Logs

~/.paperclip/instances/default/logs

Useful when onboarding works partly, but the service still behaves strangely later.

Storage and secrets

~/.paperclip/instances/default/data/storage
~/.paperclip/instances/default/secrets/master.key

Uploaded data and the secrets key live here by default.

First Login

What to do after the install actually works

Once the health check passes and the UI opens, keep the first session simple. The goal is to get one working company and one working agent, not build the whole org chart at once.

1. Create the company

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

2. Add one clear goal

A specific company goal makes the first agent easier to configure correctly.

3. Create the first agent

Start with the CEO agent and choose the adapter you actually plan to use.

4. Expand only after it works

Add more roles after the first agent can run cleanly inside the company.

Fixes

When something is wrong, start here first

These are the most common beginner problems on a Paperclip VPS and the fastest first response based on the official docs.

The app starts, but the browser cannot reach it

Run `pnpm paperclipai configure --section server` and recheck the chosen mode and URL first.

You used `--yes`, but now need team or public access

Move to the interactive server configuration path so the instance can use authenticated private or authenticated public mode.

Onboarding behaves strangely

Check `node -v`, then run `pnpm paperclipai doctor` before changing lots of settings at once.

Private hostnames do not work

Use `pnpm paperclipai allowed-hostname your-hostname` when Tailscale or private hostnames need to be trusted.

You are not sure the service is healthy

Run `curl http://localhost:3100/api/health` on the server before debugging the browser path.

Still unsure?

Go back to the setup guide and follow the install in order without skipping the mode decision.

Ready to install?

Use the setup guide for the full flow, then keep this page open as the reference

The setup guide is better for the first install. This docs page is better when you need the commands, modes, file locations, and common fixes while the VPS is already in front of you.

Open setup guide Compare plans Order Pro

Ready to launch?

Most visitors should start with Pro for a live Paperclip VPS.

Plans Order Pro