---
title: "Deploy Paperclip Codex"
description: "Hire OpenAI Codex agents into your Paperclip company"
category: "AI/ML"
url: https://railway.com/deploy/deploy-paperclip-with-codex-agents
---

# Deploy Paperclip Codex

Hire OpenAI Codex agents into your Paperclip company

**[Deploy Paperclip Codex on Railway](https://railway.com/template/deploy-paperclip-with-codex-agents)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-paperclip-with-codex-agents/manifest.json

- **Creator:** onepush
- **Category:** AI/ML

## Template content

### paperclip

- **Image:** ghcr.io/paperclipai/paperclip:2026.1012.0@sha256:1661b3dd3fdf7a9b59542d1ced464c3faf9dc8309798b4d15a9923ed32795307
- **Start command:** `/bin/sh -c "printenv PAPERCLIP_RAILWAY_BOOTSTRAP_JS > /tmp/railway-bootstrap.mjs || true; chmod 644 /tmp/railway-bootstrap.mjs; exec /usr/bin/tini -s -- docker-entrypoint.sh /bin/sh -c 'cd /app; if [ -s /tmp/railway-bootstrap.mjs ] && [ ${PAPERCLIP_RAILWAY_BOOTSTRAP_INVITE:-true} = true ]; then (node /tmp/railway-bootstrap.mjs &); fi; exec node --import ./server/node_modules/tsx/dist/loader.mjs server/dist/index.js'"`
- **Health check:** /api/health
- **Public domain:** Yes

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# Deploy and Host self hosted Paperclip Codex (Self-Hosted AI Company Running OpenAI Codex Agents) on Railway

This template runs a self-hosted Paperclip with the Codex CLI bundled, so you can hire OpenAI Codex agents into an org chart.

## About Hosting Paperclip Codex open-source software on Railway (self hosted Paperclip with OpenAI Codex agents template)

This template runs one paperclip service on port 3100 with a volume at /paperclip, plus Railway Postgres 18.

## Why Deploy Paperclip Codex, the OpenAI Codex cloud alternative on Railway (Railway Free Trial)

OpenAI Codex cloud is the easy path if you already pay for ChatGPT.

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

### Railway vs Other Hosting Providers and VPS for Paperclip Codex self hosting

Paperclip Codex needs a long-lived Node service, Postgres, and a persistent volume, so your host choice sets how much you manage yourself.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | Paperclip, Postgres 18, and the /paperclip volume deployed from one template with HTTPS handled. | A Droplet you size and patch, with Docker, proxy, and backups set up by hand. |
| AWS | One project with the app, database, and volume already connected. | Fine-grained control, but EC2, RDS, EBS, and load balancing each need setup. |
| Hetzner | A managed deploy with the bootstrap invite in the logs and no SSH work. | Low prices, but you handle OS updates, database backups, and TLS yourself. |

If you already run a VPS and like owning the box, Hetzner or DigitalOcean will serve Paperclip Codex well with the official Docker image.

## Common Use Cases for hosted Paperclip Codex

- **Codex engineer on assigned issues:** Hire a Codex agent, point its workspace at a repo on the /paperclip volume, and assign it tickets. It wakes on heartbeat and works each issue while you read the run transcript.
- **Scheduled refactor and test routines:** Use Paperclip routines to have a Codex agent write missing tests or tidy a module nightly. The session resumes across heartbeats, so it keeps its context.
- **Codex and Claude Code side by side:** Run a Codex agent on backend work and a Claude Code agent on frontend work in one org chart, under shared goals and budgets.
- **Budget-capped experiments:** Trial a new prompt template or cheaper model with a monthly budget set. When spend hits the cap, Paperclip pauses the agent automatically.
- **Code review with approval gates:** Let a Codex agent draft review notes or patches, but route repo writes through an approval gate. Codex runs with approvals bypassed by default, so the gate keeps a human in the loop.

## Dependencies for Paperclip Codex Docker hosted on Railway

Paperclip Codex runs as two Railway services: the paperclip app and a Postgres 18 database reached through DATABASE_URL.

### Deployment Dependencies for Managed Paperclip Codex Service (AI Agent Orchestration)

- **Postgres 18:** Provides DATABASE_URL, and migrations run on boot.
- **Volume at /paperclip:** Holds uploads, instance config, agent workspaces, and the local secrets key. Run one replica.
- **OPENAI_API_KEY:** Set it on the service or in the agent env, since Codex runs fail without it.
- **Generated 64-hex secrets:** BETTER_AUTH_SECRET, PAPERCLIP_AGENT_JWT_SECRET, and PAPERCLIP_SECRETS_MASTER_KEY, which encrypts company secrets, so don't change it later.

### Implementation Details for Paperclip Codex (Using Paperclip official docker image)

The image starts through tini and docker-entrypoint.sh, which chowns the volume and drops to the node user before the server starts.

## How does Paperclip Codex compare against other ways to run Codex agents on a schedule

### Paperclip vs OpenAI Codex cloud (OpenAI-hosted Codex agent)

- **Hosting and control:** Codex cloud runs in OpenAI's environment, while Paperclip Codex runs on your Railway service with your own volume and transcripts.
- **Org structure:** Codex cloud gives you tasks, while Paperclip adds an org chart, heartbeats, and per-agent budgets.
- **Governance:** Approval gates matter more here because Codex runs with approvals bypassed by default in this adapter.
- **Where Codex cloud wins:** It needs no server to run, which suits one agent doing occasional tasks.

### Paperclip vs running codex exec in CI (scripted Codex runs)

- **Scheduling:** A CI job runs codex exec when a pipeline fires, while Paperclip wakes agents on assigned issues or schedules.
- **Spend control:** CI has no per-agent budget, so a loop can burn tokens unnoticed; Paperclip pauses an agent when its budget runs out.
- **Session continuity:** Paperclip resumes Codex sessions across heartbeats, which a fresh CI container won't do.
- **Where CI wins:** It's lighter and already sits next to your code and tests.

### Paperclip vs CrewAI (Python multi-agent framework)

- **Build model:** CrewAI is a Python framework where you write the agents yourself, while Paperclip is a ready-made platform with a UI and org chart.
- **Operations:** Issues, budgets, and approvals come built in with Paperclip, while with CrewAI you build them yourself.
- **Where CrewAI wins:** If you want fine-grained control over agent logic in code, it's the more flexible tool.

### Paperclip Codex vs Claude Code agents (Anthropic CLI in Paperclip)

- **Same platform:** Both run under Paperclip's org chart, budgets, and approvals, so the choice comes down to the model CLI.
- **Adapter choice:** Paperclip Codex uses codex_local with OPENAI_API_KEY, while Claude Code uses its own adapter and Anthropic key, so you can run both side by side.
- **Where Claude Code wins:** If your team already works in Claude Code, switching adds work for little gain.

## How to use Paperclip Codex (the OSS AI agent orchestration platform)?

1. Find the `[railway-bootstrap]` block in the deploy logs and copy the one-time `/invite/pcp_bootstrap_` URL, valid for 72 hours. Open it in your browser, sign up, and you become instance admin.
2. Add `OPENAI_API_KEY` to the paperclip service variables and redeploy.
3. Create a company, then an agent with adapter Codex (local).
4. Set the model and a `cwd` on the `/paperclip` volume so work survives restarts.
5. Set a monthly budget. It pauses the agent when spend runs out, which matters because Codex bypasses approvals by default.
6. Run the environment test to confirm the CLI, working directory, and key.
7. Assign an issue, trigger a heartbeat, and read the run transcript.

```json
{
  "adapter": "codex_local",
  "model": "your-model-name",
  "cwd": "/paperclip/workspaces/backend",
  "timeoutSec": 1800,
  "outputInactivityTimeoutMs": 1800000,
  "dangerouslyBypassApprovalsAndSandbox": false,
  "env": { "OPENAI_API_KEY": "your-key-here" }
}
```

## How to self host Paperclip Codex on other VPS Services (Paperclip self hosting guide)

Paperclip runs on any VPS with Node.js and Postgres, and the Codex CLI plus your OpenAI key must sit on the same box.

### Clone the Repository

Pull the source and move into the folder.

```bash
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
```

### Install Dependencies

Install pnpm and the Codex CLI, then confirm both work.

```bash
npm install -g pnpm @openai/codex
pnpm install
codex --version
```

### Configure Environment Variables

Create a `.env` file with your database URL, public address, and secrets.

```bash
DATABASE_URL=postgres://user:pass@localhost:5432/paperclip
PAPERCLIP_PUBLIC_URL=https://your-domain
BETTER_AUTH_SECRET=your-64-hex-secret
PAPERCLIP_AGENT_JWT_SECRET=your-64-hex-secret
PAPERCLIP_SECRETS_MASTER_KEY=your-64-hex-secret
OPENAI_API_KEY=your-openai-key
```

Keep the secrets master key safe, since changing it makes stored company secrets unreadable.

### Start the Paperclip Codex Application

Build and start the server, then open your-domain to claim the first admin account.

```bash
pnpm build
pnpm start
```

Put a TLS reverse proxy in front of port 3100 and use external Postgres for production.

## Official Pricing of Paperclip Codex (Paperclip pricing)

Paperclip is MIT licensed and free to self-host, so there is no Paperclip subscription to buy.

## Paperclip Codex cloud vs self hosted comparison (Pricing, features, costs, and more)

Running Paperclip Codex yourself means you own the server, the database, and the bill for both hosting and model usage.

### Monthly cost of self hosting Paperclip Codex on Railway

Expect roughly $10-20 per month for the Paperclip app and Postgres at light use.

### System Requirements for Hosting Paperclip Codex on a VPS

Give the container at least 1 GB of RAM and a persistent volume mounted at /paperclip, since that holds uploads, agent workspaces, and the local secrets key.

## Frequently Asked Questions (FAQs)

### Do I need a ChatGPT login to run Codex agents?

No.

### Why does the agent edit files without asking me first?

By default the adapter sets dangerouslyBypassApprovalsAndSandbox to true, so Codex runs without its own approval prompts.

### Where does Codex store its state?

Paperclip seeds a managed CODEX_HOME per company under the /paperclip volume, symlinks the shared auth.json, and copies config.toml into it.

### Why did my run time out?

Runs stop when they pass timeoutSec or go quiet longer than outputInactivityTimeoutMs, which defaults to 30 minutes.

### Can I mix Codex and Claude Code agents in one company?

Yes.

### How do budgets stop a runaway agent?

Paperclip tracks spend per agent against the monthly budget you set.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius v0.1 Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/deploy-paperclip-with-codex-agents