Deploy and Host self hosted Paperclip HTTP Agents (Custom HTTP and Process Agents) on Railway

This template deploys a self-hosted Paperclip instance on Railway with Postgres 18 and a persistent volume.

About Hosting Paperclip HTTP Agents open-source software on Railway (self hosted webhook and shell-command agents for Paperclip template)

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

Railway handles the containers, public domain, health checks, and Postgres backups, so you skip running a VPS.

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

CrewAI gives you a framework for defining agent crews in Python, and you own the code that runs them.

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 HTTP Agents 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 HTTP Agents self hosting

Railway deploys Paperclip and Postgres together from one template, while a VPS leaves the whole stack to you.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	A one-click template with paperclip, Postgres 18, a persistent /paperclip volume, and migrations on boot.	A droplet you configure yourself, including Docker, a reverse proxy, backups, and Postgres.
AWS	One managed project with no IAM policies or VPC routing to set up before your first heartbeat.	Fine-grained networking and scaling, but a longer setup and more parts to maintain.
Hetzner	Managed deploys with a public domain and health checks, so no SSH or manual process supervision.	Cheap compute and bandwidth, but you own OS patching, firewalls, and keeping process agent scripts running.

Common Use Cases for hosted Paperclip HTTP Agents

Wrapping an internal service as a webhook agent: Expose an existing triage or metrics service over HTTP and point an http adapter at its URL. Paperclip POSTs to it on each heartbeat, so the service joins the company without a rewrite.
Running a Python script as a process agent: A nightly file-based reporting script can run through a process adapter on the same box. Paperclip spawns the command, so it must be runnable inside that container.
Passing taskId and wakeReason to an external agent: The http request body carries these fields, so the agent knows what it was woken for. It can call back through PAPERCLIP_API_URL and comment on the task.
Keeping custom scripts on the /paperclip volume: Store scripts under /paperclip so they survive redeploys. Anything outside that volume is lost when the container is rebuilt.
Pinning timeoutSec on long-running process agents: Set timeoutSec in adapterConfig so a stuck script cannot hold a run open forever. Choose a value that covers a normal run with some headroom.

Dependencies for Paperclip HTTP Agents Docker hosted on Railway

This template runs one paperclip service from the official Paperclip image plus Railway Postgres 18.

Deployment Dependencies for Managed Paperclip HTTP Agents Service (AI Agent Orchestration)

You need two pieces: the paperclip service and Railway Postgres, wired through DATABASE_URL.

Implementation Details for Paperclip HTTP Agents (Using Paperclip official docker image)

The start command runs tini and docker-entrypoint.sh, which fixes volume ownership and drops to the node user before starting the server.

How does Paperclip HTTP Agents compare against other ways to plug custom agents into an agent orchestration platform

Paperclip HTTP Agents vs CrewAI (Competitor Alternative)

Integration model: Paperclip treats your agent as an external hire, reached through an http webhook or a process command. CrewAI wants your agent written as a Python crew member.
Where CrewAI wins: For role-based multi-agent teams written natively in Python, CrewAI is the more direct fit.
Where Paperclip wins: Your existing service or script stays as it is, since Paperclip only needs a URL or a command.

Paperclip HTTP Agents vs AutoGen (Competitor Alternative)

Conversation vs. company: AutoGen centers on agents talking in conversations. Paperclip centers on org structure, tasks, and heartbeats.
Where AutoGen wins: For research-style multi-agent dialogue or code-execution loops, its conversation primitives are built for that.
Where Paperclip wins: Budgets sit at the company level, so a runaway custom agent is easier to cap than an open chat loop.

Paperclip HTTP Agents vs LangGraph (Competitor Alternative)

Graph vs. webhook: LangGraph models workflow as a stateful graph inside your code. With Paperclip, orchestration lives in the platform and your agent handles one wake at a time.
Where LangGraph wins: If you need fine-grained control over state transitions and branching, LangGraph gives you that directly.
Where Paperclip wins: A process agent doesn't need LangChain at all. Any language that reads env vars and exits with a code works.

Paperclip HTTP Agents vs OpenHands (Competitor Alternative)

Scope: OpenHands is built around AI software-development agents. Paperclip is a general orchestration layer that takes whatever you wire in.
Where OpenHands wins: For coding-agent work out of the box, OpenHands is the more complete product.
Where Paperclip wins: If your agent is a reporting script or internal service, you can hire it without adopting a coding-agent platform.

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

Deploy the template, open the paperclip public domain, and confirm /api/health responds.
Pick the adapter: http for a service you run elsewhere, process for a script on the same box.
For http, set adapterType to http and adapterConfig with url (required), plus optional headers and timeoutSec.
For process, set adapterType to process and adapterConfig with command (required), plus optional cwd, env, and timeoutSec. Keep scripts under /paperclip.
Process agents read PAPERCLIP_AGENT_ID and PAPERCLIP_API_KEY from their environment. Http agents get runId, agentId, companyId, and context in the webhook body. Both call back via PAPERCLIP_API_URL.
Trigger a heartbeat and check the result. Process success follows the exit code, and http captures the webhook response.

{"adapterType": "process", "adapterConfig": {"command": "python3 /path/to/agent.py", "cwd": "/path/to/workspace", "timeoutSec": 300}}

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

Running Paperclip on your own VPS works fine if you're comfortable with Postgres and TLS.

Clone the Repository

Grab the source and move into it.

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

Install Dependencies

The project uses Node.js with pnpm.

pnpm install

Configure Environment Variables

Set these before first boot. Your custom agent calls back to PAPERCLIP_API_URL, so it has to be reachable from wherever the agent runs.

export DATABASE_URL=postgres://user:password@db-host:5432/paperclip
export PAPERCLIP_PUBLIC_URL=https://paperclip.your-domain.com
export PAPERCLIP_API_URL=https://paperclip.your-domain.com
export BETTER_AUTH_SECRET=$(openssl rand -hex 32)
export PAPERCLIP_AGENT_JWT_SECRET=$(openssl rand -hex 32)
export PAPERCLIP_SECRETS_MASTER_KEY=$(openssl rand -hex 32)

Back up PAPERCLIP_SECRETS_MASTER_KEY. Changing it later makes company secrets in Postgres unreadable.

Start the Paperclip HTTP Agents Application

Start the server and confirm the health endpoint answers on port 3100.

pnpm start
curl http://localhost:3100/api/health

Railway handles the managed Postgres, public domain, TLS, and the persistent /paperclip volume for you.

Official Pricing of Paperclip HTTP Agents (Paperclip pricing)

Paperclip is MIT licensed and free to self host, so there's no Paperclip subscription to pay for the software itself.

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

Paperclip is MIT licensed, so the software is free to run. You pay for hosting, Postgres, and the model providers your agents call.

Monthly cost of self hosting Paperclip HTTP Agents on Railway

Expect roughly $10-20 per month for the Paperclip app plus Postgres at light use. Railway's $5 trial covers early testing.

System Requirements for Hosting Paperclip HTTP Agents on a VPS

Run one replica with enough memory for Node.js and your process agents. Use external Postgres for production.

Frequently Asked Questions (FAQs)

Do I need a separate server for an HTTP agent?

Not necessarily. Just make sure that URL is reachable from the Paperclip container.

What does the webhook body contain?

Paperclip sends JSON with runId, agentId, companyId, and a context object holding taskId, wakeReason, and commentId.

Does a process agent keep state between heartbeats?

The docs don't say what happens to files or memory between runs, so don't assume it does.

How do I set a timeout?

Set timeoutSec inside adapterConfig for either adapter.

How does the agent authenticate its callback to Paperclip?

Process agents get PAPERCLIP_AGENT_ID and PAPERCLIP_API_KEY injected into their environment.

Where do I put my scripts so they survive redeploys?

Put them on the /paperclip volume, which is PAPERCLIP_HOME and persists across redeploys.