Deploy and Host Paperclip with Railway

Paperclip is the app people use to manage AI agents for work: open-source orchestration for teams of AI agents, with org charts, budgets, governance, and a task manager UI. If your coding agent is an employee, Paperclip is the company.

About Hosting Paperclip

This template deploys Paperclip in authenticated mode for internet-facing use, backed by a bundled PostgreSQL 18 database with persistent storage. The image (official upstream build, pinned, plus a thin Railway start wrapper) already ships the agent CLIs (Claude Code, Codex, OpenCode, Gemini) plus git, Python, and a Rust runner, so agents can execute inside the container. A volume at /paperclip keeps workspaces, secrets, and configuration across redeploys; the database lives on its own volume.

> 🔄 Actively maintained — latest update 2026-10-28: bundled PostgreSQL upgraded to 18.6 (from 17.11). The dated change history lives in this repository's CHANGELOG.md.

DATABASE_URL is composed from the database service over Railway's private network. The manifest requests generated secrets; if the current marketplace card prompts for blank secrets, generate strong unique values before deploying. Publication of these defaults is being verified separately. The start wrapper derives PAPERCLIP_PUBLIC_URL from the public domain on each boot. Public deployments intentionally disable browser board-claim; generate an operator-only first-admin invite as described below.

Why Deploy Paperclip on Railway?

One platform: run the control plane, the database, and the agents it orchestrates in one project, connected over a private network.
Always on: agents wake for assigned work, routines fire on schedule — no laptop to keep open.
Persistent workspaces: volumes survive redeploys; sessions and skills carry over.
Scale on demand: bump memory when your agent team grows; vertical scaling takes seconds.

Common Use Cases

Orchestrate a team of coding agents (Claude Code, Codex, OpenCode, Gemini) toward shared goals with budgets and approval gates.
Run recurring routines (reports, triage, content) on cron with run history.
Give a small team a shared, governed agent workspace with cost tracking and org-level permissions.
Monitor autonomous agent work from the mobile-ready UI.

Dependencies for Paperclip Hosting

PostgreSQL 18 (bundled service, extensions preinstalled)
Docker image: upstream ghcr.io/paperclipai/paperclip:2026.1005.0, with Railway wrapper revision wotonews/paperclip:v2026.1005.0-4. Existing deployments require this image revision for paperclip-bootstrap.
Node.js 24 + pnpm, Rust runner, Python 3, git — all inside the image

Deployment Dependencies

Source: https://github.com/paperclipai/paperclip (MIT)
Docs: https://docs.paperclip.ing
CLI: npx paperclipai for local management against the deployed instance

Login credentials

Paperclip ships no default username or password — the first admin account is yours, created through a one-time operator invite:


URL	the `paperclip` service's public domain (`https://`)
Username	the email you sign up with (yours — e.g. `you@company.com`)
Password	the password you choose at signup

The invite that lets you create that account is minted by you, over SSH:

Deploy the template. If prompted, generate unique PostgreSQL and auth secrets rather than using the verification placeholders.
Generate a public domain on paperclip if absent, then redeploy so public exposure is active. Wait for deployment success.
Open Railway SSH for the paperclip service and run paperclip-bootstrap. With the CLI, use railway ssh --project --environment --service paperclip-bootstrap.
Open the printed /invite/pcp_bootstrap_... URL and create your account to become instance admin. The invite expires after 24 hours and is single-use. Treat it as a credential: never share it publicly. Running the command again before claiming rotates the invite; after an admin exists, it refuses to mint another.
Add provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, …) as service variables to enable the in-container agent CLIs, then redeploy.

The command uses the CLI already shipped in the pinned image, with a temporary credential-free config removed immediately afterward. No paperclip onboard, npm download, permanent config overwrite, or public setup endpoint is needed. Bare npx paperclipai auth bootstrap-ceo fails on env-only deployments because upstream requires a config file first.

Environment Variables

Service	Name	Required	Default	Description
postgres	`POSTGRES_PASSWORD`	yes	generated	Database superuser password.
paperclip	`BETTER_AUTH_SECRET`	yes	generated	Auth session signing secret.
paperclip	`DATABASE_URL`	no	auto-composed	Private-network Postgres URL — do not edit.
paperclip	`PAPERCLIP_PUBLIC_URL`	no	runtime-derived	Set automatically from `RAILWAY_PUBLIC_DOMAIN` by the image's start wrapper.
paperclip	`PAPERCLIP_DEPLOYMENT_EXPOSURE`	no	`public` (image default)	Set the variable to `private` to run behind a VPN.
paperclip	provider API keys	no	—	`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` enable agent CLIs.

Resource Notes

The image ships a full agent toolchain and sets a 4 GB Node heap ceiling. A 2 GB+ memory plan is recommended once agents run in-container; idle control plane fits smaller plans. Telemetry is anonymous and can be disabled with PAPERCLIP_TELEMETRY_DISABLED=1.

Local Setup

docker run -d --name paperclip -p 3100:3100 \
  -e BETTER_AUTH_SECRET=dev-secret \
  ghcr.io/paperclipai/paperclip:2026.1005.0
# UI + API on http://localhost:3100 (embedded Postgres for local use)