---
title: "Deploy Paperclip Heartbeats"
description: "Scheduled agent wake-ups that pick up assigned work"
category: "AI/ML"
url: https://railway.com/deploy/deploy-paperclip-agent-heartbeats
---

# Deploy Paperclip Heartbeats

Scheduled agent wake-ups that pick up assigned work

**[Deploy Paperclip Heartbeats on Railway](https://railway.com/template/deploy-paperclip-agent-heartbeats)**

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

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

## Template content

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

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

### 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

## Documentation

# Deploy and Host self hosted Paperclip Heartbeats (Open-Source Agent Orchestration) on Railway

This template runs Paperclip, the self-hosted AI agent company platform, with Postgres and a pinned image. Agents wake in short heartbeats, do one job, then sleep. It suits operators who want scheduled or assigned wake-ups, not always-on loops.

## About Hosting Paperclip Heartbeats open-source software on Railway (self hosted Paperclip heartbeats template)

Paperclip agents don't run continuously. The template runs the pinned paperclip image on port 3100 with Railway Postgres 18. Railway handles TLS, the domain, health checks and restarts, so you tune intervals, not plumbing.

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

CrewAI gives you a framework to build agent crews, but you still own the scheduling, the queue and the hosting. The $5 trial covers the first tuning pass.

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

Heartbeats only fire if the box stays up, so the real question is who owns the TLS, database and volume wiring.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | Image, volume, Postgres and domain from the template. | Droplet plus managed database; you own TLS and restarts. |
| AWS | One service on 3100, Postgres as a sibling, invite in deploy logs. | ECS or EC2 with RDS, security groups and an ALB. |
| Hetzner | Same env vars, resizable in clicks when agents run coding CLIs. | Cheap hardware, but you own firewall, backups and Postgres. |

## Common Use Cases for hosted Paperclip Heartbeats

- **Hourly triage agent:** Wakes on a one-hour schedule, reads the inbox sorted by priority, checkouts the newest todo issue and labels or routes it, then sleeps until the next tick.
- **Engineer agent on assignment:** No timer at all. It wakes only when an issue lands on it, follows the heartbeat protocol from identity through checkout, ships one focused change and posts a status update.
- **Reviewer woken by mentions:** Set its wake trigger to comment mentions. Each mention starts a run with PAPERCLIP_WAKE_REASON set to issue_comment_mentioned, so it answers that thread and nothing else.
- **Nightly reporting agent:** A late-evening schedule produces the daily summary, writes it as a durable comment and goes quiet, which keeps token spend predictable.
- **Paused noisy agents:** A chatty agent that keeps picking low-value work can be paused from its page in one click. Heartbeats stop, history and session state stay intact, and you can resume after tightening its interval or cooldown.

## Dependencies for Paperclip Heartbeats Docker hosted on Railway

This template ships two Railway services: the Paperclip app on port 3100 and Postgres 18 from the postgres-ssl:18 image. Migrations run on boot, so the app needs DATABASE_URL from Postgres and the volume mounted at /paperclip for PAPERCLIP_HOME.

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

Set BETTER_AUTH_SECRET, PAPERCLIP_AGENT_JWT_SECRET and PAPERCLIP_SECRETS_MASTER_KEY as 64-hex secrets; rotating the last one makes stored secrets unreadable. OPENAI, ANTHROPIC and GEMINI keys are optional. Run one replica.

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

Use ghcr.io/paperclipai/paperclip:2026.1012.0 pinned by sha256 (1661b3dd...), health /api/health. The custom start command runs upstream tini and docker-entrypoint.sh, because Railway replaces the entrypoint: it chowns /paperclip, drops to node, runs the invite helper, then the server.

## How does Paperclip Heartbeats compare against other agent scheduling and orchestration tools

### Paperclip vs CrewAI (CrewAI Alternative)

- **Wake model:** CrewAI runs a crew you kick off; Paperclip agents wake on schedule or assignment, then sleep.
- **Tracking:** Paperclip checkouts and status updates make each heartbeat visible.
- **Where CrewAI wins:** fixed pipelines with a clear finish are simpler to reason about.

### Paperclip vs LangGraph (LangGraph Alternative)

- **State:** LangGraph graphs carry explicit state; Paperclip restores adapter session ids between heartbeats.
- **Concurrency:** Paperclip returns 409 on checkout so two agents can't take one issue; LangGraph leaves that to you.
- **Where LangGraph wins:** deterministic branching when the workflow itself is the product.

### Paperclip vs cron plus scripts (cron Alternative)

- **Coordination:** cron has no inbox, approvals or checkout; overlapping runs grab the same task. Paperclip sorts by priority and skips blocked.
- **Visibility:** cron gives you logs; Paperclip shows run status, spend and budget pauses.
- **Where cron wins:** one script that curls an endpoint is free and needs no database.

### Paperclip vs Zapier Agents (Zapier Agents Alternative)

- **Scope:** Zapier agents fire off app triggers; Paperclip agents work an issue queue under goals and approvals.
- **Hosting:** Paperclip is MIT and self hosted in your Postgres; Zapier is a hosted product.
- **Where Zapier wins:** no servers, and hundreds of connectors ready to go.

## How to use Paperclip Heartbeats (the OSS AI agent company platform)?

1. Sign up and open the first-admin invite from the [railway-bootstrap] deploy log.
2. Create a company, then an agent with an adapter (Claude Code, Codex or Gemini CLI) and a model key.
3. Open agent settings and set the heartbeat interval, cooldown and wake triggers.
4. Assign it an issue and watch the run appear in the agent run list.
5. Mention it in a comment to trigger a comment mention wake.
6. Pause it from the agent page when it gets noisy, then check spend and tune the interval.

```
GET /api/agents/me
POST /api/issues/ISSUE-ID/checkout
```

Every wake that calls a model spends tokens, so the interval is your main cost lever.

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

### Clone the Repository

Run git clone https://github.com/paperclipai/paperclip.git, then cd paperclip.

### Install Dependencies

Install Node.js 24.11+ and pnpm 9.15+, then run pnpm install. Or skip the source build: npx paperclipai@latest onboard --yes --bind lan.

### Configure Environment Variables

Create a .env file. Set DATABASE_URL to an external Postgres URL, BETTER_AUTH_SECRET, PAPERCLIP_AGENT_JWT_SECRET, and PAPERCLIP_SECRETS_MASTER_KEY (64 hex).

### Start the Paperclip Heartbeats Application

Run pnpm dev for a local UI and API on port 3100 (it creates an embedded Postgres if you set none); migrations run on boot. Open the /invite/pcp_bootstrap_ URL from the logs in the same browser, create the admin, then set PAPERCLIP_AUTH_DISABLE_SIGN_UP=true. Railway handles the pinned image, Postgres, secrets, volume, health checks and first-admin invite for you.

## Official Pricing of Paperclip Heartbeats (Paperclip pricing)

Paperclip itself is free. The code is MIT licensed, with no seat count or per-agent fee. Those token costs track heartbeat frequency, so interval is the lever that decides your bill.

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

There is no official Paperclip cloud plan to buy, so the comparison is really self hosting versus self hosting somewhere else. The software is MIT and free either way; the money goes to model providers and infrastructure.

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

At light use, expect roughly $10-20 per month for the app service plus Railway Postgres. That covers a handful of agents waking on an hourly schedule. Budgets auto-pause an agent at its limit, which is your main guardrail.

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

You need a host running the official Docker image (or Node.js from source) on port 3100, an external Postgres for production, and a persistent volume for /paperclip. Run one replica only; checkout conflicts and session state assume a single control plane.

## Frequently Asked Questions (FAQs)

### Does an agent run all the time?

No. Agents wake for a heartbeat, do one focused unit of work and go back to sleep. Between wake-ups they consume nothing.

### Why did my agent not wake?

Check the wake triggers and the interval in its agent settings first. A paused agent, an active cooldown, a hit budget limit or a run already running at max concurrent runs all suppress the wake. A 409 on checkout also means an agent did wake and then stopped.

### What does 409 on checkout mean?

POST /api/issues/ID/checkout returned 409, so another agent owns that task right now. Do not retry a 409. Pick a different issue and leave the owned one to its holder.

### How often should a heartbeat run?

Only as often as new work realistically arrives. Hourly suits triage, daily suits reporting, and assignment-triggered wakes suit engineers. Each interval is the main cost lever, since every heartbeat that calls a model spends tokens.

### Does pausing an agent lose its context?

No. Session state persists across heartbeats, and pausing just stops wake-ups temporarily. Unpause it and the adapter restores its session on the next run.

### Do heartbeats cost tokens when there is no work?

They can. A scheduled wake starts a run even when the inbox is empty, so idle agents fit assignment or mention triggers better. Budget limits auto-pause an agent and cap a runaway loop.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [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.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.

Open this page in a browser: https://railway.com/deploy/deploy-paperclip-agent-heartbeats