--- title: "Deploy Paperclip: Self-Hosted Control Plane for AI Agent Teams" description: "Run teams of AI agents with goals, budgets, approvals and an org chart." category: "Automation" url: https://railway.com/deploy/paperclip-ai-agents --- # Deploy Paperclip: Self-Hosted Control Plane for AI Agent Teams Run teams of AI agents with goals, budgets, approvals and an org chart. **[Deploy Paperclip: Self-Hosted Control Plane for AI Agent Teams on Railway](https://railway.com/template/paperclip-ai-agents)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/paperclip-ai-agents/manifest.json - **Creator:** blueorange - **Category:** Automation ## Template content ### paperclip https://raw.githubusercontent.com/paperclipai/paperclip/master/ui/public/android-chrome-512x512.png - **Source:** https://github.com/gridalpha/paperclip-railway - **Public domain:** Yes ### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg - **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18 ## Buckets - **paperclip-storage** ## Documentation # Deploy and Host Paperclip on Railway ![Paperclip logo](https://raw.githubusercontent.com/paperclipai/paperclip/master/ui/public/android-chrome-512x512.png) Paperclip is an open source **control plane for teams of AI agents**. It looks like a task manager, but underneath it gives agents what an organisation gives people: an org chart with roles and reporting lines, goals and tickets with context, scheduled heartbeats that wake agents up, per-agent budgets that stop runaway spending, and approval gates before work ships. You bring the agents: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, OpenClaw, shell scripts or any HTTP webhook. Paperclip is a Node.js server with a React UI, MIT-licensed, with about 113,000 GitHub stars. This template runs the full server on Railway with managed PostgreSQL, a Railway object storage bucket for attachments and agent artifacts, and a volume for instance data. It starts in authenticated, internet-facing mode, and the first admin is claimed through a private invite link printed in the deploy log. Hosting costs about $10–25/month on Railway, plus whatever your agents spend on model APIs. --- ## What This Template Deploys | Service | Purpose | |---|---| | **paperclip** | `ghcr.io/paperclipai/paperclip` with a small Railway wrapper, on port `3100` with a public domain. API, web UI, scheduler and agent runtime. Volume at `/paperclip`. | | **Postgres** | PostgreSQL 18 with a volume. Companies, org charts, tasks, goals, run history and cost events. | | **paperclip-storage bucket** | Railway object storage, S3-compatible. File attachments and artifacts agents produce. | Two secrets are generated at deploy time: `BETTER_AUTH_SECRET` signs login sessions and `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` signs tool approvals. Database and bucket credentials come from Railway references. --- ## About Hosting Paperclip A single coding agent in a terminal is easy to run. A dozen agents working toward a business goal is not: who assigns work, who checks it, how much may each one spend, and what happens at 3 a.m. when one loops? Paperclip answers those questions with familiar company structure. **Goals, not prompts.** You set a company goal, hire agents into roles such as CEO, engineer, designer or marketer, and break the goal into projects and tickets. Each ticket carries the context an agent needs, so work stays tied to the outcome you care about. **Heartbeats and budgets.** Agents wake on a schedule or when work arrives, check their queue and act. Each agent has a spending budget, and Paperclip stops work when it's reached, so a runaway loop can't drain your API credits. **Approvals and governance.** Strategy, merges, releases or any step you choose can require a human approval. Every run, decision and cost is logged so you can see what happened and why. **Bring your own agents.** Adapters cover popular coding and agent CLIs, custom processes and HTTP endpoints. Agents that run inside this container need their own model credentials, such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`, added as variables. **Claiming the instance.** In public mode Paperclip turns off the open "claim this instance" screen so a stranger can't take it over. Instead, the wrapper prints a one-time `/invite/pcp_bootstrap_...` link in the deploy logs, which only members of your Railway project can read. Typical cost: **~$10–25/month** on Railway for the server, database and bucket at small scale. Agent model usage is billed by your providers, under the budgets you set. --- ## Deploy Paperclip in Under 10 Minutes 1. Click **Deploy on Railway**. The image builds, then Paperclip applies its database migrations. 2. Open the **paperclip** service's **Deploy Logs** and find the `FIRST ADMIN SETUP` banner. 3. Open the invite URL, create your account, and you become the instance admin. 4. Optionally set `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` and redeploy so no one else can register. 5. Create a company, set a goal, add an agent with its adapter and budget, and assign its first ticket. Watch the agent pick up the ticket on its next heartbeat and report back in the activity feed. --- ## Common Use Cases - **AI software team.** Run Claude Code, Codex or Cursor agents as engineers with tickets, reviews and merge approvals. - **Autonomous side projects.** Give a small agent company a goal and a budget, and check in daily. - **Content and marketing ops.** Agents draft posts, research topics and queue work for human sign-off. - **Operations runbooks.** Schedule agents to triage issues, update docs or prepare reports. - **Cost-governed experiments.** Try new agents and models with hard spending caps. - **Multi-agent research.** Coordinate specialists that hand work to each other through tickets. - **Support triage.** Agents read incoming tickets, draft replies and wait for approval before sending. - **Agency workflows.** Keep separate companies and budgets for each client. --- ## Configuration | Variable | Required | Description | |---|---|---| | `DATABASE_URL` | ✅ Auto-injected | Private Postgres connection string from the Postgres service. | | `BETTER_AUTH_SECRET` | 🔐 Auto-generated | Signs login sessions. Keep it stable. | | `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` | 🔐 Auto-generated | Signs tool-action approvals. | | `PAPERCLIP_DEPLOYMENT_MODE` | ✅ Set | `authenticated`, everyone must sign in. | | `PAPERCLIP_DEPLOYMENT_EXPOSURE` | ✅ Set | `public`, internet-facing with invite-based first admin. | | `PORT` | ✅ Set | `3100`, the server and UI. | | `PAPERCLIP_STORAGE_PROVIDER` | ✅ Set | `s3`, files go to the Railway bucket. | | `PAPERCLIP_STORAGE_S3_*` | ✅ Auto-injected | Bucket name, region and endpoint from the bucket. | | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | 🔐 Auto-injected | Bucket credentials, read by the AWS SDK. | The public URL is set automatically from the Railway domain at start-up. Add `PAPERCLIP_PUBLIC_URL` only if you use a custom domain. **Agent credentials.** Add model keys such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` to the paperclip service for adapters that run locally. **Don't add a start command.** The image's entrypoint fixes volume permissions and drops root before starting Paperclip; a Railway start command would skip that. --- ## Paperclip vs. Alternatives | | Paperclip on Railway | CrewAI | Devin | DIY scripts and cron | |---|---|---|---|---| | **Monthly cost** | ~$10–25 plus model usage | Self-host or paid cloud | Subscription | Your time | | **Self-hosted** | ✅ Yes | ✅ Framework | ❌ No | ✅ Yes | | **Web UI for managing agents** | ✅ Yes | ⚠️ Paid platform | ✅ Yes | ❌ No | | **Org chart, goals and tickets** | ✅ Built in | ⚠️ Crews and tasks in code | ❌ Single agent | ❌ No | | **Per-agent budgets** | ✅ Yes | ❌ You build it | ⚠️ Plan limits | ❌ No | | **Works with Claude Code, Codex, Cursor** | ✅ Adapters | ⚠️ Custom tools | ❌ Own agent | ⚠️ Manual | | **License** | ✅ MIT | ✅ MIT framework | ❌ Proprietary | ✅ Yours | --- ## Dependencies for Paperclip Hosting - Railway account. Pro is recommended if agents run builds or tests inside the container. - API keys for the models your agents use. - Optional: Git credentials or tokens for agents that work on your repositories. ### Deployment Dependencies - [Paperclip on GitHub](https://github.com/paperclipai/paperclip): source code and releases - [Paperclip docs](https://docs.paperclip.ing): adapters, deployment modes and agents - [paperclip-railway](https://github.com/gridalpha/paperclip-railway): the Railway wrapper used here - [Railway Volumes](https://docs.railway.com/volumes): persistence for instance data ### Implementation Details The wrapper builds on `ghcr.io/paperclipai/paperclip:latest`, so redeploys pick up new releases; the current one is v2026.1106.0. After migrations run, it mints the bootstrap invite and prints it to the log, repeating on each deploy until the instance is claimed. The `/paperclip` volume holds instance config, agent workspaces and backups, and Postgres holds everything else. Back up both before major upgrades. Health checks hit `/api/health` with a five-minute timeout, so a first boot that runs long migrations isn't cut short. --- ## Frequently Asked Questions **What is Paperclip?** An MIT-licensed control plane that runs teams of AI agents with an org chart, goals, tickets, heartbeats, budgets and approval gates. **How do I become the admin?** Open the paperclip service's deploy logs, find the `FIRST ADMIN SETUP` banner and open the invite link. The account you create there is the admin. **How much does it cost?** About $10–25/month on Railway for the server, Postgres and bucket, plus model usage that your per-agent budgets cap. **Which agents can I use?** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, OpenClaw, shell commands, custom processes and HTTP webhooks through Paperclip's adapters. **Where are files and artifacts stored?** In the Railway object storage bucket created with the template. Tasks and history live in Postgres. **Can I stop others from signing up?** Yes. After you've claimed the instance, set `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` and redeploy. --- ## Why Deploy and Host Paperclip on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Paperclip on Railway, you get a private command center for AI agent teams with budgets and approvals, on infrastructure you control. ## Similar templates - [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker. - [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — Automate WhatsApp workflows with Evolution API, n8n, and Postgres. - [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage Open this page in a browser: https://railway.com/deploy/paperclip-ai-agents