Deploy Paperclip

Deploy and Host Paperclip on Railway

Paperclip is an open-source control plane for running teams of AI agents at work. It looks like a task manager, but underneath is the scaffolding an organisation of agents needs: an org chart with roles and reporting lines, tickets carrying goal context, heartbeats that wake agents on a schedule, per-agent budgets that stop runaway spend, and approval gates before anything ships. Agents are yours to bring — Claude Code, Codex, Cursor, Gemini, OpenCode, bash, or any HTTP webhook.

Self-host Paperclip on Railway and you get the full server, not a trimmed demo. This template runs the Node.js API and React interface as one service in front of managed PostgreSQL, with a Railway object storage bucket for attachments and the artifacts agents produce. Tasks, org structure, run history and cost events live in Postgres, and a persistent volume keeps instance config, execution workspaces and backups across redeploys. The image comes from ghcr.io/paperclipai/paperclip with a thin startup wrapper handling first-admin setup.

Getting Started with Paperclip on Railway

After the deploy turns green, open the service's Deploy Logs and find the FIRST ADMIN SETUP banner, followed by a URL ending in /invite/pcp_bootstrap_…. Open it, choose a name, email and password, and that account becomes the instance administrator. A fresh link is issued on every deploy until someone claims the instance, so a missed log is never a lockout.

Claiming the invite starts a five-step setup: name the company, state its mission, create a team lead, pick its adapter and model, confirm. Paperclip creates your first ticket and opens the dashboard. Add a task with New Task, open Org to see reporting lines, and check Costs — if your task survives a refresh, the app and database are working. Straight after claiming, set PAPERCLIP_AUTH_DISABLE_SIGN_UP to true so nobody else can register; leave it unset until then, because your own first signup uses that endpoint. To run agents you supply model provider keys — the image ships the Claude Code, Codex, OpenCode and Gemini CLIs but no credentials. Until a key is set, runs fail in about a second and tickets show "Recovery needed", while tasks, org chart, budgets and audit history work fully.

About Hosting Paperclip

Anyone running more than a couple of coding agents hits the same wall: a dozen terminal tabs, no record of who is doing what, no budget ceiling, and every context reset losing the thread. Paperclip replaces that with a durable system of record — work is ticket-based and agent sessions survive restarts, because their state lives in Postgres.

• Bring your own agent — Claude Code, Codex, Cursor, Gemini, OpenCode, bash and webhook adapters
• Goal alignment — every task carries its goal ancestry, so agents see the "why", not just a title
• Heartbeats — agents wake on a schedule, pick up work, and delegate across the org chart
• Cost control — token and spend tracking per agent, project and model, with hard stops
• Governance — approval gates, revisioned config, and pause, resume or terminate on any agent

The architecture is deliberately small. The Paperclip service runs the API and compiled interface in one Node.js process, so there is a single origin and no cross-domain cookie problems. PostgreSQL is the system of record, the bucket holds attachments and work products, and the volume at /paperclip carries instance config, agent workspaces and backups.

Why Deploy Paperclip on Railway

Railway supplies the pieces Paperclip needs without any assembly:

• Managed PostgreSQL provisioned and wired up automatically
• Object storage for attachments, no separate file server
• A persistent volume for workspaces and backups
• HTTPS on a generated domain, custom domains supported

Common Use Cases

• Running a small autonomous product team — give a lead agent a mission, let it delegate research, code and marketing, and review output through approval gates
• Taming a fleet of coding agents — replace untracked terminal sessions with tickets that survive a reboot
• Recurring operational work — schedule support triage, weekly reports or social posts
• Controlling agent spend — per-agent budgets pause a runaway loop before it drains your quota

Dependencies for Paperclip

• Paperclip server — ghcr.io/paperclipai/paperclip:latest, built from paperclipai/paperclip (MIT). API and interface on port 3100, health at /api/health.
• PostgreSQL — Railway managed Postgres, holding every company, agent, ticket, run, cost event and session. Migrations apply at startup.
• Object storage bucket — Railway managed S3-compatible storage for attachments and work products.
• Volume at /paperclip — instance config, agent execution workspaces and scheduled backups.

Environment Variables Reference

Deployment Dependencies

• Source: paperclipai/paperclip · image ghcr.io/paperclipai/paperclip
• Documentation: docs.paperclip.ing
• Runtime: Node.js 20+ with PostgreSQL 15 or newer

Hardware Requirements for Self-Hosting Paperclip

Agent execution drives usage: the control plane is light, but agents checking out git worktrees and building code need CPU and volume headroom.

Self-Hosting Paperclip with Docker

Outside Railway, use the published image with PostgreSQL. A minimal Compose file:

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: paperclip
      POSTGRES_USER: paperclip
      POSTGRES_DB: paperclip
  server:
    image: ghcr.io/paperclipai/paperclip:latest
    ports: ["3100:3100"]
    environment:
      DATABASE_URL: postgres://paperclip:paperclip@db:5432/paperclip
      PAPERCLIP_DEPLOYMENT_MODE: authenticated
      BETTER_AUTH_SECRET: change-me
    volumes: ["paperclip-data:/paperclip"]
volumes:
  paperclip-data:

To run from source, clone the repository and start it with pnpm — an embedded PostgreSQL is created automatically:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip && pnpm install && pnpm dev

Is Paperclip Free to Self-Host?

Paperclip is open source under the MIT licence, with no paid tiers, seat limits or feature gates in the self-hosted build. No account is required and nothing phones home. Your costs are the Railway resources the template uses, plus whatever you spend with model providers, since agent runs bill to your own API keys.

FAQ

What is Paperclip? An open-source Node.js and React application that orchestrates teams of AI agents, giving them an org chart, tickets, budgets, schedules and approval gates so they work toward a goal with a human supervising rather than babysitting.

What does this Railway template deploy? A Paperclip server from the official image, a managed PostgreSQL database, an object storage bucket, and a volume for config, workspaces and backups. Only the Paperclip service is publicly reachable.

How do I log in to Paperclip the first time? Open the service's Deploy Logs and find the FIRST ADMIN SETUP banner. The URL beneath it is a single-use invite, and the account you create there becomes the instance admin. Public deployments intentionally have no open "claim this instance" screen, so nobody who finds the URL can take ownership.

Why does this template include PostgreSQL and object storage? PostgreSQL is the system of record for every company, agent, ticket, run and cost event, and lets agent sessions survive a restart. Object storage keeps attachments out of the database.

Which AI agents work with self-hosted Paperclip? Claude Code, Codex, Cursor, Gemini and OpenCode have first-class adapters, and anything reachable over HTTP can be a webhook agent. You supply the provider keys; Paperclip stores them encrypted and injects them only into the runs that need them.

How do I stop other people signing up on my instance? Set PAPERCLIP_AUTH_DISABLE_SIGN_UP to true once you have claimed the instance. Registration is then rejected at the API, while existing accounts log in normally.