---
title: "Deploy Paperclip"
description: "Community template for self-hosting Paperclip (AI agent orchestration)"
category: "AI/ML"
url: https://railway.com/deploy/paperclip-5
---

# Deploy Paperclip

Community template for self-hosting Paperclip (AI agent orchestration)

**[Deploy Paperclip on Railway](https://railway.com/template/paperclip-5)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/paperclip-5/manifest.json

- **Creator:** go2ai
- **Category:** AI/ML
- **Total deploys:** 9

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### Paperclip

- **Source:** https://github.com/AlehTurbal/paperclip-railway
- **Health check:** /api/health
- **Public domain:** Yes

## Documentation

# Deploy and Host Paperclip with Railway

Paperclip is an open-source Node.js and React application for running a team of
AI agents as an organisation. You define business goals, "hire" agents from any
provider, set budgets, and track work and cost from one dashboard. It looks like
a task manager; underneath it is org charts, governance and agent coordination.

*Note: this is a community template — unaffiliated and community-maintained —
for the open-source [Paperclip](https://github.com/paperclipai/paperclip)
project (MIT). It is not endorsed by or supported by Paperclip AI.*

## About Hosting Paperclip

Paperclip runs as a single Node.js process serving both its JSON API and its
React single-page UI, backed by PostgreSQL. This template wires up everything
self-hosting needs: a managed Postgres over Railway's private network, a
persistent volume mounted where Paperclip expects its home directory, generated
secrets, and a health-checked service on a public domain. The build is a thin
Dockerfile wrapper that pulls the official upstream container image, so deploys
never compile Paperclip's monorepo.

## What this template provisions

- **Paperclip** — the upstream image, with a volume at `/paperclip`, a
  healthcheck on `/api/health`, and a public domain.
- **Postgres** — managed, reached over Railway's private network.
- Generated per-deployment secrets for session signing, tool-action signing and
  credential encryption. Every deployment gets its own random values.

## Common Use Cases

- Run a standing team of AI agents against long-lived business goals, with budgets and approvals.
- Give a small team one shared dashboard for agent work, cost and governance instead of per-developer local setups.
- Coordinate mixed agent harnesses — Claude Code, Codex, Gemini, Kimi, OpenCode — from a single org chart.
- Self-host agent orchestration on infrastructure you control, with your own provider credentials and no vendor account.
- Trial Paperclip on a real public URL before committing to a heavier cloud deployment.

## ⚠️ After deploying: claim your instance immediately

Paperclip starts with **no admin and open sign-up**, and in this configuration
the first account to sign up can claim the instance. Treat the minutes after
deploying as a window to close.

1. **Open your Railway URL** and create your account.
2. **Click "Claim this instance."** You are now instance admin and owner.
3. **Close sign-up — mandatory.** Add `PAPERCLIP_AUTH_DISABLE_SIGN_UP=true` to
   the Paperclip service and redeploy. Add further users with Paperclip's
   invite flow instead.
4. **Add a provider credential** (below) so your agents can actually run.

Steps 1–3 are not optional on a public URL. Until step 3 is done, anyone who
finds the URL can create an account on your instance.

**Order matters — do not preset the variable.** The template does not set
`PAPERCLIP_AUTH_DISABLE_SIGN_UP`, and you must not add it before step 2:
claiming requires a signed-in session, so an instance that boots with sign-up
already closed cannot create its first admin. That is recoverable — set the
variable back to `false`, redeploy, then claim — but it is an avoidable round
trip. Add the variable only once you hold the admin account.

## Agent credentials: subscriptions vs API keys

| Agent | Subscription | API key |
|---|---|---|
| **Claude** (Pro/Max) | ✅ `CLAUDE_CODE_OAUTH_TOKEN` | ✅ `ANTHROPIC_API_KEY` |
| **Codex** (ChatGPT) | ✅ `codex login` inside the container | ✅ `OPENAI_API_KEY` |
| **Gemini** | paid-tier CLI auth or API key | ✅ `GEMINI_API_KEY` / `GOOGLE_API_KEY` |
| **Antigravity** | ❌ no Paperclip adapter | — |
| **Kimi** | — | ✅ |
| **OpenCode** | — | ✅ (any supported provider key) |

**Claude on a subscription** is the smoothest path. Run `claude setup-token` on
your own machine, then store the result in Paperclip as a user secret named
`CLAUDE_CODE_OAUTH_TOKEN`. Your agents then bill against your Claude plan
rather than metered API usage.

**Codex on a ChatGPT subscription** needs its credential file inside the
container: `railway ssh` into the Paperclip service, then `codex login`. The
credentials land in `/paperclip/.codex`, which is on the volume and survives
restarts.

**Fix the ownership afterwards.** `railway ssh` connects as `root` but the
Paperclip server runs as `node`, so the login is written `root:root` mode `600`
and the server cannot read it — the agent then fails with
`configuration_incomplete` ("no Codex credentials available for managed home
..."). Run `chown -R node:node /paperclip/.codex` in the same session, or just
restart the service: the upstream entrypoint repairs ownership under
`$PAPERCLIP_HOME` on every boot. Paperclip seeds each agent's managed home from
that host login at launch. Binding a per-agent `OPENAI_API_KEY` secret takes
precedence over the host login and avoids the problem entirely.

Paperclip enables strict secret handling in authenticated mode, so pasting a
raw value into a field named `*_API_KEY`, `*_TOKEN` or `*_SECRET` is rejected
in favour of a secret reference. That is intended — create the secret, then
bind it.

## Configuration

Fixed deployment settings (bind host, deployment mode, proxy trust, migrations,
heartbeat) are baked into the image. Only genuinely per-deployment values are
Railway variables:

- `DATABASE_URL` — managed Postgres reference (set by the template).
- `PAPERCLIP_PUBLIC_URL` / `PAPERCLIP_ALLOWED_HOSTNAMES` — derived from your
  Railway domain. Append any custom domain to the allowlist and update the
  public URL, or Paperclip will reject requests for it.
- `BETTER_AUTH_SECRET`, `PAPERCLIP_AGENT_JWT_SECRET`,
  `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET`, `PAPERCLIP_SECRETS_MASTER_KEY` —
  generated fresh per deployment.

**Back up `PAPERCLIP_SECRETS_MASTER_KEY`** somewhere other than this
deployment. It encrypts every credential Paperclip stores; without it, a
restored database is unrecoverable ciphertext.

`PAPERCLIP_AUTH_DISABLE_SIGN_UP` is **not** set by this template and closing
sign-up is mandatory once you hold the admin account — see the claim steps
above. Add it as `true` on the Paperclip service after claiming, never before.

Optional: `PAPERCLIP_VERSION` pins the Paperclip release. It is not preset by
this template — add it yourself on the Paperclip service and redeploy, and the
Dockerfile's own default (`latest`) applies until you do. Accepted values:
`latest` | `beta` | `nightly` | `canary` | an exact version like `2026.410.1`,
or an exact commit like `sha-1a2b3c4`.
Never use the `-cloud` tags — those are amd64-only.

## Dependencies for Paperclip Hosting

- **PostgreSQL** — provisioned by this template as a managed Railway Postgres service.
- **A persistent volume** — mounted at `/paperclip`, for the secrets master key, uploads, agent workspaces, git checkouts, run logs and agent-CLI credentials.
- **The upstream Paperclip image** — `ghcr.io/paperclipai/paperclip`, multi-arch (amd64/arm64).
- **At least one AI provider credential** — to actually run agents. Paperclip boots without one, so you can add it after deploying.

### Deployment Dependencies

- [Paperclip repository](https://github.com/paperclipai/paperclip) (MIT)
- [Paperclip documentation](https://docs.paperclip.ing)
- [Upstream container image and release channels](https://github.com/paperclipai/paperclip/blob/master/doc/CHANNELS.md)
- [Paperclip Discord](https://discord.gg/m4HZY7xNG3)

## Why Deploy Paperclip on Railway?

Railway is a singular platform to deploy your infrastructure stack. By
deploying Paperclip on Railway you get the database, persistent volume, public
HTTPS endpoint and healthchecks provisioned for you, and one place to scale
everything as your agent fleet grows.

## Operational notes

- **Sizing.** Upstream's own reference deployment asks for **2 vCPU / 4 GB**.
  Agent runs are not cheap; this is not a free-tier template.
- **Redeploys briefly interrupt traffic.** Railway will not mount one volume
  into two live deployments, so a service with a volume has short downtime on
  redeploy even with a healthcheck configured.
- **Ports.** Railway injects its own `PORT` at runtime (8080), overriding the
  image's `PORT=3100`. If a deployment shows healthy but the URL returns
  "Application failed to respond" (502), the public domain's target port is
  stale — point it at the port the app actually listens on.
- **Agents spawn many processes.** The image runs `tini` as PID 1 to reap them.
  Do not set a custom start command that bypasses the entrypoint.
- **Agent runs have no wall-clock limit by default.** Paperclip reports
  `Adapter execution timeout: none` unless you set `adapterConfig.timeoutSec`
  on the agent. On metered infrastructure a stuck run bills until you notice
  it, so set a ceiling per agent.
- **Updating.** Your service deploys from this template's repo but lands with
  no GitHub repo trigger, so it will not auto-deploy when that repo changes.
  To move to a newer Paperclip release, redeploy the service — with
  `PAPERCLIP_VERSION` unset the Dockerfile default (`latest`) pulls the current
  image. Pin `PAPERCLIP_VERSION` if you would rather choose when that happens.

## Licence

This Railway configuration is MIT licensed. Paperclip itself is MIT licensed
by Paperclip AI.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/paperclip-5