How it works

The services

Your Railway project has three services.

Service	What it does	Address	Kept on a volume
CloudCLI	Claude Code (and Codex) in your browser, the /setup page, and the scheduled-jobs skill that manages jobs.	Public	The home folder: sign-ins, chats, repo clones, installed tools.
Paperclip	Runs the jobs and keeps every run. Its dashboard shows jobs, tasks, runs and transcripts.	Public	Paperclip’s data: database dumps, uploaded files, its own repo checkouts, plugins.
Postgres	Paperclip’s database: jobs, tasks, runs.	Private	The database.

Both apps use the same login: the email and password from the deploy form. CloudCLI talks to Paperclip’s API over Railway’s private network, with a key the template creates at start.

A job

A job is a schedule plus a one-line prompt naming a skill in one of your repos. For example:

Part	Example	Where it lives
Title	Weekday open issues digest	Paperclip, and .claude/jobs.json
Schedule	0 8 * * 1-5 in America/Toronto	Paperclip, and .claude/jobs.json
Prompt	Run the open-issues-digest skill.	Paperclip, and .claude/jobs.json
What to do	The steps of the digest	.claude/skills/open-issues-digest/SKILL.md in your repo

The job’s logic lives in the skill, in git. The job only says when, and which skill. In Paperclip, a job is a routine.

A run

When a job’s time comes:

1. Paperclip opens a task for the Runner agent. The task’s title names the job, and its description is the job’s prompt.

2. The Runner starts Claude Code on Paperclip’s own checkout of the job’s repo. It runs git pull first, so it always uses what is pushed.

3. Claude runs the skill the task names, and only that.

4. Claude closes the task in the same run: done with a one-line summary, or blocked with the reason. When a login or token is missing, it says so and stops, rather than looking for credentials.

Paperclip keeps the run: its status, the summary, the full transcript, the model, the tokens and the duration.

The Runner agent

The Runner is the Paperclip agent the template creates for your jobs. It:

• runs Claude Code itself (the claude command), with your Claude sign-in from the setup page;
• uses Sonnet by default, which you can change on the Runner’s page in Paperclip;
• wakes only for its tasks, never on a timer;
• follows short instructions the template keeps up to date: pull first, run the named skill, close the task in the same run, keep changes inside the repo, and commit or push only when the skill says so.

An optional second agent, Codex, runs the jobs you give it with OpenAI’s Codex. See Codex.

One Paperclip project per repo

Each repo you connect on the setup page gets its own project in Paperclip, with the repo as its workspace. A job belongs to one repo, and its runs use a checkout of that repo only.

• The first repo takes the project Paperclip starts with, renamed after the repo.
• Each later repo gets a new project named after it.
• A job goes in the project of the repo you were chatting in when you asked for it.

See Several repos.

What Claude knows in CloudCLI

At every start, the template writes a short block of instructions into Claude Code’s user settings on CloudCLI (~/.claude/CLAUDE.md). It tells Claude, in every chat:

• what this server is, and which repos are connected;
• that a job belongs to the repo of the current chat;
• that jobs run in Paperclip as the Runner, with links to give you;
• to use the scheduled-jobs skill for anything about jobs;
• your time zone, and the setup page’s address;
• how to explain the server when you say hi or seem unsure where to start;
• what is still missing on the setup page.

The scheduled-jobs skill teaches Claude the rest: how to create and change jobs, record them in git, test them and read their cost.

Tip

You never have to name the skill. Ask for what you want (“every Monday, summarize last week’s commits”) and Claude uses it.