Deploy and Host self hosted Paperclip Budgets (Open-Source AI Agent Orchestration) on Railway

This template runs Paperclip on Railway with Postgres 18, pinned to 2026.1012.0. Budgets are the point: monthly UTC or lifetime caps per agent, company or project, warning at 80 percent, hard stop at 100 percent. Built for teams running agents.

About Hosting Paperclip Budgets open-source software on Railway (self hosted Paperclip budgets template)

You own the data. Railway supplies the domain, TLS, volume and deploy logs, so you set the first monthly cap instead of wiring compose files.

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

CrewAI gives you the crew; it doesn't stop the bill. Paperclip ships monthly and lifetime budgets per agent, company or project, with a hard pause at 100 percent on day one. Spin it up on the Railway $5 trial and set a cap before the first heartbeat.

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 Budgets 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 Budgets self hosting

The budget engine is identical everywhere; what changes is the wiring you do before your first heartbeat.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	Postgres and the image deploy as two services, DATABASE_URL wired	A droplet plus a managed Postgres cluster, set up by hand
AWS	A small bill and one place to watch agent spend	ECS or EC2, RDS, secrets and networking to assemble first
Hetzner	Cheap containers with the volume at /paperclip	The lowest raw compute, but you own Docker and backups

Budgets still pause agents at 100 percent on every one of these.

Common Use Cases for hosted Paperclip Budgets

The scope you pick decides who stops spending when the money runs low. These are the five setups I reach for.

Monthly cap per agent: give each agent a calendar-month budget in UTC, so a chatty researcher and a quiet linter don't share one pot.
Company-wide ceiling: a company-scope policy catches spend the per-agent caps miss and hard-stops the whole org at 100 percent.
Lifetime budget for a one-off project: put a lifetime amount on a project scope and it never resets until you raise it.
Runaway loop catcher: the 80 percent warning fires first, then the hard stop pauses the agent and cancels the run in progress.
Finance spend view: Audit > Budgets breaks spend down per agent, so finance sees the number before the provider invoice lands.

Dependencies for Paperclip Budgets Docker hosted on Railway

Two services make up the template: paperclip on port 3100 with health at /api/health and a volume at /paperclip (PAPERCLIP_HOME, holding uploads, instance config, agent workspaces and the secrets key), plus Railway Postgres 18 supplying DATABASE_URL. Migrations run on boot.

Deployment Dependencies for Managed Paperclip Budgets Service (AI Agent Orchestration)

Three 64-hex secrets are generated: BETTER_AUTH_SECRET for sessions, PAPERCLIP_AGENT_JWT_SECRET for agent tokens and PAPERCLIP_SECRETS_MASTER_KEY for company secrets; rotating the last makes stored ones unreadable. Model keys are optional.

Implementation Details for Paperclip Budgets (Using Paperclip official docker image)

The image is ghcr.io/paperclipai/paperclip:2026.1012.0, pinned by sha256. The [railway-bootstrap] block in the deploy logs holds the one-time invite URL.

How does Paperclip Budgets compare against other agent cost controls

All four cap spend, but the cap sits in a different layer of the stack.

Paperclip vs CrewAI (CrewAI Alternative)

Where Paperclip wins: caps sit on the agent, company or project, with an 80 percent warning and a hard stop at 100 percent.
Windows: monthly UTC calendar month or lifetime; CrewAI leaves spend caps to your own code.
Where CrewAI wins: a code-first Python framework with deeper orchestration primitives.
Honest gap: a CLI adapter that reports no dollar cost leaves that agent effectively uncapped.

Paperclip vs LangGraph (LangGraph Alternative)

Where Paperclip wins: pause, resume and Audit > Budgets ship in the UI; LangGraph needs your own callbacks and kill switch.
Resume path: raise the budget and resume, or wait for 00:00 UTC on the 1st.
Where LangGraph wins: finer graph control and a managed platform for stateful graphs.
Honest note: both only see the spend their adapters report.

Paperclip vs LiteLLM budgets (LiteLLM Alternative)

Where Paperclip wins: the cap sits beside tasks and heartbeats, so hitting it stops the agent, not one request.
Governance: agent, company and project scopes plus a Budget Override approval for board sign-off.
Where LiteLLM wins: a multi-provider proxy with key and team spend limits plus routing and fallbacks.
Best of both: run LiteLLM behind Paperclip for request-level caps and let Paperclip pause the agent.

Paperclip vs Zapier Agents (Zapier Agents Alternative)

Where Paperclip wins: monthly or lifetime caps, auto-pause, heartbeat frequency as a cost lever, no per-agent fee.
Where Zapier wins: nothing to run and thousands of app integrations.
Second fence: neither replaces usage limits set in the OpenAI or Anthropic console.

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

Open the [railway-bootstrap] invite URL from the deploy logs, sign up in the same browser, and become instance admin.
Create a company, add an agent, and attach a model key.
Set a monthly budget on the agent, with the 80 percent warning and the 100 percent hard stop, or use the API:

PATCH /api/agents/AGENT_ID/budgets
{"budgetMonthlyCents": 2500}

Start a heartbeat and watch spend.
At 80 percent you see a warning. At 100 percent Paperclip pauses the agent, cancels the run, and stops heartbeats. Tasks stay assigned.
Raise the budget and resume from Audit > Budgets.

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

Same budgets and pauses, on your own box. These steps get Paperclip running with a model key so budgets have something to meter.

Clone the Repository

Check out a tagged release, not main.

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
git checkout v2026.1012.0

Install Dependencies

Docker with Compose is the documented path; a source install needs Node.js 24.11+ and pnpm 9.15+. The image already bundles the claude, codex, opencode and gemini CLIs the local adapters call.

Configure Environment Variables

The quickstart reads a host port and a data directory, which holds embedded Postgres, uploads, the secrets key and agent workspaces. For production, point DATABASE_URL at external Postgres.

export PAPERCLIP_PORT=3100
export PAPERCLIP_DATA_DIR=../data/pc

Start the Paperclip Budgets Application

docker compose -f docker/docker-compose.quickstart.yml up --build

Terminate TLS in nginx or Caddy and back up the data directory. Railway does Postgres, secrets, the volume, health checks and the invite URL for you.

Official Pricing of Paperclip Budgets (Paperclip pricing)

The software is MIT licensed and free to self-host. There's no per-agent fee and no Paperclip subscription to buy. Model provider tokens are billed separately. Budgets themselves cost nothing extra: the 80 percent warning and the hard stop at 100 percent ship with the image.

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

There is no Paperclip cloud plan to compare against, since Paperclip is MIT software you host yourself. The real question is hosting plus tokens versus a managed cost layer.

Monthly cost of self hosting Paperclip Budgets on Railway

Light use runs about $10-20 a month for the container plus Postgres, more if agents run coding CLIs inside it. Add provider tokens, and remember there is no per-agent fee, so ten agents cost the same in software as one.

System Requirements for Hosting Paperclip Budgets on a VPS

Node.js and pnpm to build from the repo, or Docker for the official image, plus a Postgres 18 database you back up. Production wants external Postgres, one replica, a persistent /paperclip volume and all three 64 hex secrets left alone.

Frequently Asked Questions (FAQs)

What happens when an agent hits 100 percent of its budget?

With the hard stop on, Paperclip pauses the agent with pause reason budget, cancels the run in progress and stops heartbeats. Tasks stay assigned; it just stops waking up.

Does a paused agent lose its tasks?

No. Assigned tasks stay assigned, so after you raise the budget and resume, the agent picks up the same queue.

When do monthly budgets reset?

At 00:00 UTC on the 1st of the calendar month, for policies with windowKind calendar_month_utc. Lifetime budgets never reset.

Can I set a budget for a whole company?

Yes. Post scope, amountCents, warnPercent and hardStopEnabled to /api/companies/COMPANY_ID/budgets/policies. A company ceiling catches a team of agents drifting together.

How is spend measured?

Paperclip counts what agent adapters report per run, tokens and cost. Subscription-based CLI adapters may not report dollars, so treat that spend as unknown, not zero.

Should I still set provider limits?

Yes, always. Paperclip's cap depends on adapters reporting honestly, so set usage limits in the OpenAI or Anthropic console as a second fence.