Deploy Paperclip

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 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

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 (MIT)
• Paperclip documentation
• Upstream container image and release channels
• Paperclip Discord

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.