Deploy Paperclip

Deploy and Host Paperclip with Railway

Paperclip is the app people use to manage AI agents for work: open-source orchestration for teams of AI agents, with org charts, budgets, governance, and a task manager UI. If your coding agent is an employee, Paperclip is the company.

About Hosting Paperclip

This template deploys Paperclip in authenticated mode for internet-facing use, backed by a bundled PostgreSQL 17 database with persistent storage. The image (official upstream build, pinned, plus a thin Railway start wrapper) already ships the agent CLIs (Claude Code, Codex, OpenCode, Gemini) plus git, Python, and a Rust runner, so agents can execute inside the container. A volume at /paperclip keeps workspaces, secrets, and configuration across redeploys; the database lives on its own volume.

Wire-up is automatic: DATABASE_URL is composed from the database service over Railway's private network and BETTER_AUTH_SECRET is generated at deploy time. The image's start wrapper derives PAPERCLIP_PUBLIC_URL from the service's runtime public domain — regenerate or change the domain and it follows on the next deploy. On first boot Paperclip runs its schema migrations and prints a one-time board-claim URL in the deploy logs — open it to become the instance admin (see below).

Why Deploy Paperclip on Railway?

• One platform: run the control plane, the database, and the agents it orchestrates in one project, connected over a private network.
• Always on: agents wake for assigned work, routines fire on schedule — no laptop to keep open.
• Persistent workspaces: volumes survive redeploys; sessions and skills carry over.
• Scale on demand: bump memory when your agent team grows; vertical scaling takes seconds.

Common Use Cases

• Orchestrate a team of coding agents (Claude Code, Codex, OpenCode, Gemini) toward shared goals with budgets and approval gates.
• Run recurring routines (reports, triage, content) on cron with run history.
• Give a small team a shared, governed agent workspace with cost tracking and org-level permissions.
• Monitor autonomous agent work from the mobile-ready UI.

Dependencies for Paperclip Hosting

• PostgreSQL 17 (bundled service, extensions preinstalled)
• Docker image: upstream ghcr.io/paperclipai/paperclip:2026.1005.0, published as wotonews/paperclip:v2026.1005.0-3 with a Railway start wrapper
• Node.js 24 + pnpm, Rust runner, Python 3, git — all inside the image

Deployment Dependencies

• Source: https://github.com/paperclipai/paperclip (MIT)
• Docs: https://docs.paperclip.ing
• CLI: npx paperclipai for local management against the deployed instance

First Boot: Claim Your Instance

1. Deploy the template (set the two secrets when prompted — both can be auto-generated — and the defaults work as-is).
2. Generate a public domain on the paperclip service if one was not created.
3. Open the deployment logs and find the line printing the board-claim URL: /board-claim/?code=<code>.
4. Visit that URL on your instance and sign in — you become the instance admin.
5. Add provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, …) as service variables to enable the in-container agent CLIs, then redeploy.

Environment Variables

Resource Notes

The image ships a full agent toolchain and sets a 4 GB Node heap ceiling. A 2 GB+ memory plan is recommended once agents run in-container; idle control plane fits smaller plans. Telemetry is anonymous and can be disabled with PAPERCLIP_TELEMETRY_DISABLED=1.

Local Setup

docker run -d --name paperclip -p 3100:3100 \
  -e BETTER_AUTH_SECRET=dev-secret \
  ghcr.io/paperclipai/paperclip:2026.1005.0
# UI + API on http://localhost:3100 (embedded Postgres for local use)