Deploy and Host Paperclip on Railway

Paperclip is an open-source control plane for organizing teams of AI agents around goals, roles, tasks, approvals, budgets, and persistent operational context. This template runs Paperclip's official immutable image as one authenticated Railway service, with durable application state stored on a required Railway volume.

About Hosting Paperclip

Hosting Paperclip involves serving its web application, running its embedded PostgreSQL database, preserving its local secrets key and agent workspaces, and connecting selected agent runtimes. This template uses one service and one volume mounted at /paperclip, exposes port 3100 over Railway HTTPS, and checks /api/health. The official image includes Claude Code, Codex, OpenCode, and Gemini CLIs. Provider credentials remain optional deployer inputs, while gateway and HTTP adapters connect to separately operated endpoints. One replica is required because the embedded database and mounted volume are single-writer state.

Common Use Cases

Coordinate coding and operational agents from one control plane.
Run bundled local CLI adapters with deployer-owned provider credentials.
Connect separately hosted gateways and HTTP agents to a persistent Paperclip instance.

Dependencies for Paperclip Hosting

Paperclip's official multi-platform OCI image.
A Railway persistent volume, HTTPS domain, and generated authentication secret.

Deployment Dependencies

Review the Paperclip Docker deployment guide, Paperclip adapter overview, and Railway volume documentation before updating the pinned image or storage layout.

Implementation Details

The service uses the immutable image ghcr.io/paperclipai/paperclip@sha256:17e54b1fd1ffcc3a575cf6c23cd6c364f89cf67614481a4176749d1c6a293507. Mount paperclip-data at /paperclip, keep one replica, target port 3100, and use /api/health as the health check. Generate BETTER_AUTH_SECRET once with ${{secret(64, "0123456789abcdef")}}.

The deploy form offers optional empty secret inputs for OPENAI_API_KEY (Codex), ANTHROPIC_API_KEY (Claude Code), GEMINI_API_KEY or GOOGLE_API_KEY (Gemini), OPENROUTER_API_KEY, and XAI_API_KEY. Paperclip starts without them, so provide only the keys needed by the adapters you configure. Prefer Paperclip's encrypted secret bindings after onboarding instead of sharing a service-level provider key with every agent.

Why Deploy 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 are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.