Deploy and Host Paperclip on Railway

Paperclip is open-source (MIT) orchestration for running a company with AI agents. You set goals, hire agents — Claude Code, Codex, OpenCode, Gemini, Hermes, OpenClaw and more — give them budgets and heartbeats, and Paperclip coordinates the work through org charts, tickets, tool approvals and governance, so the day-to-day runs without you dispatching every task by hand.

This template deploys it as two services — the app on a persistent volume plus a managed PostgreSQL — from the official upstream image, pinned to a release commit. The deploy form has nothing you have to fill in.

About Hosting Paperclip

Paperclip is a Node monorepo that also ships the agent CLIs it drives, so hosting it is mostly about three things: what gets built, what persists, and whether the agents can actually act. This template differs from the other Paperclip listings on all three.

No build step. Upstream publishes an official production image for every commit. This template runs ghcr.io/paperclipai/paperclip pinned to the image built from the current release, so a deploy is an image pull. Every other listing forks a template repo that clones the monorepo and runs pnpm install --frozen-lockfile plus three package builds on your build minutes — and the most-deployed one still pins its clone to a release from April, thirteen releases back.
Tool approvals are configured, so hired agents can actually do work. Paperclip signs approval-required tool actions with PAPERCLIP_TOOL_ACTION_SIGNING_SECRET. That variable has no default and no fallback anywhere in the codebase: when it is unset, the tool gateway cancels the pending approval, marks the invocation failed with signing_secret_unconfigured, and returns HTTP 500 — on an instance that boots and looks perfectly healthy. This template generates it per deploy.
The volume actually works. Paperclip's current release cannot write a Railway volume at all: it only repairs ownership of its home directory when the container asks for a UID remap, which Railway never does, so it drops privileges onto a root-owned mount and dies on its first mkdir. This template runs that release image with the ownership repair applied — the same fix upstream landed on 2026-07-31, ahead of its first tagged release. The volume at /paperclip keeps the instance config, local file storage and the credentials for the bundled agent CLIs across redeploys, and the container still drops to an unprivileged user. That is also why this template sets no start command: a Railway start command replaces an image's entrypoint instead of adding to it.

Access is authenticated out of the box: the image ships PAPERCLIP_DEPLOYMENT_MODE=authenticated (the codebase's default when that is unset is no auth at all), Better Auth guards the API, and the first person to sign in claims the instance-admin role. Sign in as soon as the deploy is green.

Sizing: the app is comfortable on ~1 GB of RAM idle, and grows with how many agents you run concurrently; PostgreSQL is small. Both scale vertically on Railway without a redeploy.

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.

Agents that keep working when your laptop sleeps — heartbeats, schedules and long-running agent tasks need an always-on host, which is exactly the wrong job for a local install.
Nothing to configure — every variable arrives pre-filled: the database URL, the auth secret, the tool-signing secret and the public URL are all derived or generated at deploy time.
No surprise upgrades — the app image is built from a specific upstream release commit rather than tracking upstream's master branch, so a restart does not move you onto whatever landed today.
Your keys and your data stay yours — provider credentials, agent output and company data live in your own container and your own Postgres, not in a hosted middleman.

Common Use Cases

Running an AI agent company — goals, org charts, budgets and heartbeats across a team of agents, coordinated instead of prompted one at a time.
A shared agent workbench for a team — one always-on instance where several people hire agents, review tool approvals and watch the ticket board, instead of everyone running their own local agent.
Automating a back office — recurring work (research, reporting, triage, follow-ups) handed to scheduled agents with per-agent spend caps.
Comparing agent stacks on the same task — Claude Code, Codex, OpenCode and Gemini adapters ship in the same image, so the same ticket can be run through different agents.

Dependencies for Paperclip Hosting

PostgreSQL — included in this template as a managed service with its own volume. Paperclip reads DATABASE_URL and applies its migrations on boot; without an external database it falls back to an embedded PostgreSQL that is refused outright for public deployments.
A persistent volume at /paperclip (included). It holds the instance config, local file storage and the agent CLIs' credentials — without it, every redeploy signs your agents out.
API keys for the model providers you want to use — Anthropic, OpenAI and others. Added inside Paperclip after you sign in, not at deploy time; nothing external is required to get the service running.

Deployment Dependencies

Paperclip — the upstream open-source project (MIT)
Paperclip documentation — product overview and setup guides
ghcr.io/paperclipai/paperclip — the official image this template builds on
bon5co/paperclip-railway — the thin Railway-tuned wrapper this template deploys (official release image + the volume-ownership fix)

Implementation Details

After the deploy finishes:

Open your Railway domain and create the first account. The first signed-in user claims instance admin, so do this immediately.
Add your model-provider credentials in Paperclip, then create a company, hire agents and set budgets and heartbeats.
Health check at any time:

curl https:///api/health

Custom domains. The instance runs with a hostname allow-list (that is what keeps a private deployment private). Your Railway domain is on it automatically. If you add a custom domain later, append its hostname to PAPERCLIP_ALLOWED_HOSTNAMES — comma-separated — or requests to it are refused with a 403.

Upgrading. The app image tracks upstream releases; redeploy the service to pick up the current build. Migrations apply on boot, so back the database up first.