Deploy and Host self hosted Paperclip Gemini CLI (AI Agent Company Running Gemini CLI) on Railway

This template deploys a Paperclip company server with Postgres, so you can hire Gemini CLI agents into an org chart and run them on heartbeats within budgets.

About Hosting Paperclip Gemini CLI open-source software on Railway (self hosted Paperclip with Gemini CLI agents template)

This template runs the Paperclip server and its React UI as one paperclip service on port 3100, backed by a Railway Postgres 18 database that Paperclip reaches through DATABASE_URL.

Why Deploy Paperclip Gemini CLI, the CrewAI alternative on Railway (Railway Free Trial)

CrewAI is a solid open-source Python framework, but it gives you scripts, not an org chart you can run.

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 Gemini CLI 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 Gemini CLI self hosting

Paperclip needs a Node.js server, a React UI, and Postgres, so the real question is how much of that you want to run yourself.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	Paperclip, Postgres 18, and a public domain from one template, with the volume and secrets handled.	A droplet you configure yourself: Docker, Postgres, TLS, and patching.
AWS	A running paperclip service and Postgres with no VPC or IAM setup first.	Full control and scale, but you own networking, RDS sizing, and IAM policies.
Hetzner	A managed deploy with migrations on boot and a stable volume at /paperclip.	Cheap raw compute, but you handle the OS, backups, and reverse proxy yourself.

Railway costs more per hour than a bare VPS, but for a small team of agents the saved setup time usually matters more.

Common Use Cases for hosted Paperclip Gemini CLI

Gemini research agent on a heartbeat: Give a Gemini CLI agent a recurring research goal and a timer heartbeat, so it checks for new work on a schedule and posts findings back to its issue without you prompting it each time.
Mixed-model company: Run a Gemini CLI agent for cheap bulk reading next to Claude Code and Codex agents that handle the harder coding, all under one org chart with shared goals.
Budget caps per agent: Set a spend limit on each agent so an experimental Gemini worker can't quietly burn through your provider budget, with threshold alerts before work pauses at the limit.
Unattended runs with yolo mode: Enable the adapter's yolo flag (it passes --approval-mode yolo) for overnight jobs that shouldn't stall on approval prompts, and keep the cwd tightly scoped because yolo trusts the agent's actions.
Session resume across heartbeats: Let the agent pick up the same Gemini session on its next wake, so it remembers earlier work in the same directory instead of starting cold every time.

Dependencies for Paperclip Gemini CLI Docker hosted on Railway

This template runs as two services: the paperclip app on port 3100 and a Railway Postgres 18 database wired in through DATABASE_URL.

Deployment Dependencies for Managed Paperclip Gemini CLI Service (AI Agent Orchestration)

Railway Postgres 18: supplies DATABASE_URL; migrations run on boot.
Volume at /paperclip: this is PAPERCLIP_HOME, holding uploads, instance config, agent workspaces, and the local secrets key.
Port 3100: the app listens here, with a health check at /api/health.
Generated secrets (64 hex each): BETTER_AUTH_SECRET, PAPERCLIP_AGENT_JWT_SECRET, and PAPERCLIP_SECRETS_MASTER_KEY.
Optional LLM key: GEMINI_API_KEY is empty by default, so set it before Gemini agents can run.

Implementation Details for Paperclip Gemini CLI (Using Paperclip official docker image)

The template uses the official Paperclip image with a start command that runs tini and docker-entrypoint.sh, since Railway replaces the ENTRYPOINT when a start command is set.

How does Paperclip Gemini CLI compare against other ways to run teams of AI agents

Paperclip Gemini CLI vs CrewAI (Crewai Alternative)

Where CrewAI wins: It's an open-source Python framework, so if your team wants crew logic written as code, it's the more direct fit.
Where Paperclip differs: You get an org chart, goals, budgets, and approval gates in a UI instead of wiring roles and tasks together in a script.
Gemini angle: The gemini_local adapter runs the real Gemini CLI on a heartbeat and resumes sessions between wakes.

Paperclip Gemini CLI vs AutoGen (Autogen Alternative)

Where AutoGen wins: It's a Microsoft open-source framework built for multi-agent conversations, which suits back-and-forth dialogue.
Where Paperclip differs: Agents are treated as employees with assigned issues and scheduled heartbeats, not as chat participants.
Budget control: Company, agent, and project budgets track reported spend and pause work at set limits.

Paperclip Gemini CLI vs Devin (Devin Alternative)

Where Devin wins: It's a commercial autonomous engineer from Cognition that runs in its own sandbox, so setup is far lighter for one coding task.
Where Paperclip differs: You host the agents yourself, mix Gemini CLI with Claude Code and Codex agents, and govern them as a company.
Tradeoff: Devin is the faster start for a single job, while this stack asks you to host and configure the company yourself.

Paperclip Gemini CLI vs OpenHands (Openhands Alternative)

Where OpenHands wins: It's an open-source platform for AI software agents that write and run code, a strong pick when code execution is the whole job.
Where Paperclip differs: Paperclip coordinates many agents across goals and issues with heartbeats and governance, rather than one coding loop.
Tradeoff: OpenHands is simpler for one capable coding agent, and Paperclip pays off once you have several agents to coordinate.

How to use Paperclip Gemini CLI (the OSS AI agent orchestration platform)?

Once the deploy is green, here's the first-day run order.

Open the deploy logs, find the [railway-bootstrap] block, and copy the one-time /invite/pcp_bootstrap_ URL. It's valid for 72 hours. Open it in the same browser, sign up, and you become the instance admin.
On the paperclip service, add GEMINI_API_KEY with your Google AI Studio key, then redeploy. Nothing runs without a key or local Gemini CLI auth.
Create an agent and pick the Gemini CLI adapter (gemini_local).
Set cwd to an absolute path the container can write to, and set model (it defaults to auto).
Click Test Environment. It checks the CLI install, the working directory, the key hint, and a live probe.
Assign the agent an issue and watch the heartbeat run in the activity feed.

adapter: gemini_local
cwd: /paperclip/workspaces/research
model: auto
yolo: false
timeoutSec: 600
graceSec: 15
env:
  GEMINI_API_KEY:

How to self host Paperclip Gemini CLI on other VPS Services (Paperclip self hosting guide)

Running this on your own VPS works fine since the upstream project is MIT licensed and needs Node.js and an external Postgres.

Clone the Repository

Grab the source and move into the folder.

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

Install Dependencies

Paperclip uses pnpm, so install the packages with it.

pnpm install

Configure Environment Variables

Set the database URL and the three generated secrets.

export DATABASE_URL="postgres://user:pass@your-db-host:5432/paperclip"
export BETTER_AUTH_SECRET="your-64-hex-secret"
export PAPERCLIP_AGENT_JWT_SECRET="your-64-hex-secret"
export PAPERCLIP_SECRETS_MASTER_KEY="your-64-hex-secret"
export PAPERCLIP_PUBLIC_URL="https://your-domain"
export GEMINI_API_KEY="your-gemini-key"

Start the Paperclip Gemini CLI Application

Start the server, then open your-domain and use the one-time bootstrap invite from the startup output to sign up as admin.

Official Pricing of Paperclip Gemini CLI (Paperclip pricing)

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

Paperclip Gemini CLI cloud vs self hosted comparison (Pricing, features, costs, and more)

Paperclip is MIT licensed and free to run, so the real choice is hosting it yourself or paying for a managed instance.

Monthly cost of self hosting Paperclip Gemini CLI on Railway

Expect roughly $10-20 a month for the Paperclip app plus Railway Postgres at light use.

System Requirements for Hosting Paperclip Gemini CLI on a VPS

Plan for a small Linux box with enough RAM for the Node.js server and Postgres, with the gemini command installed on the same host.

Frequently Asked Questions (FAQs)

Should I set GEMINI_API_KEY or GOOGLE_API_KEY?

The adapter accepts either name, and this template only wires GEMINI_API_KEY by default.

Why does Test Environment fail on my Gemini agent?

Almost always the probe has no working key or local auth to use, so it reports a failed environment test instead of a silent runtime error.

Does the Gemini agent remember context between heartbeats?

Yes.

How risky is yolo mode?

Yolo mode passes --approval-mode yolo, so the agent runs without stopping for approval.

How do budgets stop a runaway Gemini agent?

Company, agent, and project budgets track the spend Paperclip records, raise alerts at thresholds, and pause work at the limit.

Do Gemini agents pick up my skills?

Yes.