Deploy and Host Paperclip on Railway

Paperclip is an open-source Node.js and React app for running a team of AI agents as an organisation. Hire Claude Code, Codex, OpenCode or Gemini agents into an org chart, give them roles, managers, budgets and long-lived goals, then approve and audit their work from one board. This template deploys it with Postgres and a volume holding the thing the quickstart glosses over: agent credentials.

What This Template Deploys

Service	Purpose
`paperclip`	Node server and React UI, public HTTPS domain. Agents run inside this container.
`Postgres`	Org chart, agents, projects, tasks, runs, budgets and audit history. Volume attached.
Volume	Agent credentials and runtime home directory.

Read the first row carefully. Paperclip is an orchestrator, not a sandbox host — the Claude Code and Codex processes it manages run as subprocesses inside that container, with whatever access it has.

About Hosting

Paperclip self-hosts cleanly. Getting agents to actually authenticate is where every deployment stalls, and the obvious route is the one that does not work.

The in-UI login buttons do not work on a self-hosted instance. Paperclip's in-browser sign-in flows for Claude and Codex each acquire a sandbox lease, and sandbox providers are not bundled in the self-hosted image. Clicking them is the first thing anyone tries, and it fails. Authenticate out of band: CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY for Claude, and for Codex, railway ssh into the service and run codex login there.

Codex credentials land in a specific place, and ownership matters. The image sets HOME=/paperclip, so a login inside the container writes to /paperclip/.codex — on the volume, surviving restarts. Follow it with chown -R node:node /paperclip/.codex or the agent fails with configuration_incomplete and a message about no Codex credentials for the managed home, which reads like a missing login rather than a permissions fault.

Agents run inside your container, not in a sandbox. Budgets and approvals are real and useful, but they cap spend, not reach. An agent working a task has the container's filesystem and whatever credentials you put there. Give scoped repository access rather than broad tokens, and decide what you are comfortable with before assigning a long-lived goal.

Subscription auth is cheaper and raises a question worth answering. CLAUDE_CODE_OAUTH_TOKEN bills agent work against your Claude Pro or Max plan rather than metered API, which changes the economics substantially. Those are individual subscriptions, and driving a standing team of agents from one on a server is worth checking against your provider's terms first.

One gigabyte is not enough. Railway's trial caps each service at 1 GB, and because agents run inside the Paperclip container rather than beside it, memory scales with how many work at once. Budget for concurrency, not the idle server.

Autonomy is the feature and the risk. Long-lived goals mean agents act while nobody watches. Set per-agent budgets and approval gates before the first goal, not after the first surprise — overspend pausing an agent is a backstop, not a plan.

Typical cost: ~$25–45/month for Paperclip and Postgres at $10/GB/month RAM, $20/vCPU/month CPU and $0.15/GB/month volumes, driven almost entirely by concurrent agent memory. Model usage bills separately to your provider or your subscription.

How It Compares

	Paperclip	Claude Code alone	Beevibe	CI pipelines
Multiple agents, one goal	Yes, org chart	No	Yes	No

The honest edge: if you run one agent at a time and watch it, Claude Code alone is simpler — keep using it. Beevibe takes the opposite bet, orchestration in the cloud and execution on your own machine via a local daemon, which keeps code and filesystem off the server entirely and is the better choice if that matters more than everything living in one place. Paperclip earns its place when you genuinely have several agents on several projects and have lost track of which is doing what.

Deploy in Under 5 Minutes

Click Deploy and pick a workspace. Paperclip and Postgres come up wired, with the volume mounted on the agent home directory.
Give the service more than 1 GB of memory before adding agents.
Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in Variables. Do not use the in-UI login button — it needs a sandbox provider this image does not include.
For Codex: railway ssh into the service, codex login, then chown -R node:node /paperclip/.codex.
Hire one agent, give it a small scoped task with a low budget, and watch the run complete before you build an org chart.

Verify before you rely on it: redeploy the service, then run that same agent again. If it authenticates without a fresh login, credentials are on the volume. If it returns configuration_incomplete, the volume or the ownership is wrong.

Common Use Cases

Many agents, one board — stop losing track of which of twenty Claude Code sessions is doing what; every run is attributable to an agent and a task.
Long-lived goals — hand over an objective spanning days rather than a prompt spanning a session, with managers and approvals in between.
Budgeted autonomous work — per-agent spend caps, so an agent that loops cannot run up a bill unattended.

Configuration

Variable	Required	Description
`DATABASE_URL`	Auto	Reference variable on the private Postgres hostname.
`CLAUDE_CODE_OAUTH_TOKEN`	One of	Claude Pro/Max subscription auth. Bills to your plan, not metered API.
`ANTHROPIC_API_KEY`	One of	Metered API alternative to the token.
Storage volume	Pre-set	Mounted on the agent home directory, holding credentials written by `codex login`.

Skip the in-UI login buttons. They require a sandbox lease from a provider the self-hosted image does not bundle. Use environment variables, or railway ssh plus codex login inside the container.

Chown the credential directory after logging in. Without chown -R node:node /paperclip/.codex, agents fail with configuration_incomplete and the error points at missing credentials rather than at permissions.

Dependencies for Paperclip Hosting

Railway account — ~$25–45/month, dominated by memory for concurrent agents. 1 GB is below the floor.
Bundled services — managed Postgres for org, task and run state, wired over private networking.
Volume — required, holding agent credentials and the runtime home directory.
At least one provider credential — a Claude subscription token, an Anthropic or OpenAI API key, or a Codex login inside the container. Paperclip orchestrates agents; it supplies none.

Deployment Dependencies

Implementation Details

Paperclip runs the official image on a pinned tag behind Railway's HTTPS edge, with Postgres reached by private hostname through a reference variable. The image sets HOME=/paperclip, which is why the volume mounts there rather than at a conventional data path — credential directories are written relative to that home, so a volume anywhere else leaves authentication in a container layer the next deploy replaces.

The execution model is worth understanding before you scale it. Agent harnesses are subprocesses of the Paperclip server, so concurrency is bounded by one container's CPU and memory rather than spread across services. Three agents at once is three processes plus their tool invocations alongside the orchestrator. Sizing is therefore a function of concurrent agents, and the container's own credentials and filesystem are the effective permission boundary for every agent in the org chart.

Postgres holds everything durable: agents, projects, tasks, runs, budgets and the audit history that makes autonomous work reviewable. Back it up on a schedule and back up the volume alongside it — the database knows an agent exists, the volume holds the credential that lets it work. Restore one without the other and you get an org chart full of agents that cannot authenticate.

Frequently Asked Questions

Why does the Claude or Codex login button do nothing? Those flows request a sandbox lease, and sandbox providers are not included in the self-hosted image. Authenticate with environment variables or with codex login inside the container.

Where do Codex credentials live? Under the container's home directory at /paperclip/.codex, which sits on the volume. Run chown -R node:node on it after logging in.

Do agents run in a sandbox? No. They run as subprocesses inside the Paperclip container with its filesystem and credentials. Budgets limit spend, not access.

Can I use my Claude subscription instead of API billing? Yes, via CLAUDE_CODE_OAUTH_TOKEN. Check your plan's terms before running a standing team from it.

How much memory does it need? More than 1 GB. Agents execute in-container, so memory scales with concurrent agents, not request volume.

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 get the parts that are not in the quickstart — a volume on the home directory where agent credentials actually land, authentication that works without the sandbox the self-hosted image lacks, Postgres on the private network, and memory sized for agents that run inside the container rather than beside it.