Explainer · companion to the map

Crank Architecture

Where the work runs, and when to use what

The Agent Engineering Map shows how agents build and prove their work. This page shows where it happens. Crank’s agents work in three places: a shared computer called the box, Cursor’s cloud agents and a Mac mini at home. Finished work runs on two services outside Crank: Railway and Cloudflare Pages. Git, in between, holds everything that must last, and a person signs off before anything merges or reaches a client. Every term is explained the first time it appears.

Where Crank’s work runs. Read top to bottom: agents work on the local side, whatever must last goes into git, a person signs off, and finished work runs on the external side. Flow 3 shows a job’s results coming back the other way.

Part L · local Where do agents work? The box Cloud agents The Mac mini
Part X · external Where does finished work run? Railway Cloudflare Pages
Part W · when to use what Which place for which job? Two questions At a glance
Part F · example flows What does it look like end to end? 1 Educational page 2 Shared check 3 Ads digest 4 UI verify
Part R · rules What holds everywhere? Durable truth in git Draft, not merge No send without Peter Secrets out of skills

How to read it: each part starts with two diagrams and a short explanation. Parts L and X then have one card per place: what it is, what to use it for, what not to use it for and where its work ends up. The four flows are examples, not a record of how every job runs.

Local where agents work. External where finished work runs. Example an example flow. Crank practice marks decisions Peter and Cal have locked for Crank.

Three words first

Local

The side where Crank’s agents do the work: the box, Cursor’s cloud agents and the Mac mini. Cloud agents run on Cursor’s computers, far away, but they count as local here because that’s where work gets made.

External

Downstream: the services where finished work runs for people. Here that’s Railway, for services and scheduled jobs, and Cloudflare Pages, for websites.

Durable truth

Anything that must outlast the machine it was made on: code, notes, receipts. At Crank it lives in git. Anything that’s only on one machine is scratch.

In the map’s kitchen picture, this page is the floor plan: where the cooks work, where the order book is kept and where plates leave the kitchen. Git is the order book, the record that outlasts any one cook. Every plate passes a person on its way out, and anything for a client passes Peter.

Part L · three places

Where do agents work? · local

The box, Cursor’s cloud agents and the Mac mini: where work gets made.

L1 · Three shapes of computer. The box is one computer with a desktop for each agent. Each cloud agent gets a whole computer and ends with a draft PR on Origin. The Mac mini shares previews over Tailscale, a private network.

L2 · Scratch and durable. Anything on one machine is scratch, however useful it is. Committing it to git is the only way across. The diagrams that script drew are in git, inside this page.

Crank’s agents work in three places. The box is one shared Linux computer. Each agent on it gets its own desktop and browser, so it can use websites and apps the way a person would. Cursor cloud agents each get a whole computer of their own, in Cursor’s cloud, and many can run at once. They change code: each one works on a branch and opens a draft PR on Origin, where Crank’s code lives. The Mac mini is a small computer at home. It shows unmerged pages as private previews over Tailscale, and runs experiments from Origin repos. It isn’t for day-to-day Crank ads work. All three are scratch space: whatever must last goes into git.

Crank practice None of these machines is the record. Code goes to Origin as a draft PR, and notes and receipts go into vault-c-peter. Cursor describes its agents’ PRs as merge-ready, but at Crank they stay drafts until a person merges them.

The box

Local

What it is: One shared Linux computer for Crank’s Grok Bot agents. Each agent gets its own desktop and browser on it.
Use it for: Agent work in a browser or a desktop app, and running crank-tools commands, alongside other agents.
Not for: Keeping the only copy of anything. Files on the box are scratch.
Where its work ends up: In git: notes and receipts in vault-c-peter. Anything for a client waits as a draft for Peter.

Cursor cloud agents

Local

What it is: Agents that each run on a remote computer of their own, a VM (virtual machine), in Cursor’s cloud. Many can run at once.
Use it for: Editing a repo’s code. Each agent works on its own branch and opens a draft PR on Origin, with proof such as screenshots. This page was made this way.
Not for: Merging its own PR. Cursor’s docs call its PRs merge-ready. At Crank they stay drafts until a person merges them.
Where its work ends up: A branch and a draft PR on Origin. The computer itself is scratch.

The Mac mini

Local

What it is: A small computer at home that works as a helper: a home worker.
Use it for: Private previews of unmerged pages, shared over Tailscale. Experiments from Origin repos. Outbox copies.
Not for: Day-to-day Crank ads work.
Where its work ends up: Previews show pages that live in a draft PR, and last only while they’re switched on. Anything that must last goes into git.

Not covered here: what the outbox copies hold. Peter’s brief lists them without detail.

From the docs: Cursor’s cloud agent docs (the computers, snapshots and secrets) and Tailscale’s docs on Serve. The places, and how Crank uses them, are from Peter’s brief.

Go deeper: the local side

Cursor’s docs say cloud agents run in isolated VMs in the cloud with full development environments instead of on your local machine, and You can run as many agents as you want in parallel. Like agents on the box, They can also use computers to control the desktop and browser. What sets them apart here is the workflow: cloud agents are where repo code changes, through draft PRs on Origin.
Scratch doesn’t mean lost at once. Cursor keeps snapshots, Encrypted point-in-time copies of the virtual machine disk, for up to 90 days without use. A snapshot still isn’t the record: nobody reviews it, other agents can’t read it, and it expires.
Keys reach a cloud agent from Cursor’s settings, as environment variables, and Secrets are injected when an agent starts. An agent that’s already running won’t see a key added later, so start a new one.
Previews from the Mac mini: Tailscale Serve shares a page only with devices on the same private network, the tailnet, and its access rules still apply. Tailscale Funnel would share it with the whole internet. Tailscale’s setup notes for Serve say Funnel is enabled by default and can be turned off on a device that doesn’t need it. For unmerged or client work, use Serve, and turn Funnel off.

↑ Back to the overview

Part X · two places

Where does finished work run? · external

Railway and Cloudflare Pages: downstream, where finished work runs for people.

X1 · Two kinds of place to run. Railway runs code: a program that stays on, or a job on a timer. Cloudflare Pages runs none of your code. It sends built pages to each visitor.

X2 · From merge to live, for this site. The intended path: a person merges a draft PR, then the site is built and goes live. The dashed step isn’t written down yet, and on 7 October 2026 the live site didn’t match main.

Finished work runs on two services outside Crank. Railway runs code on its own computers. That can be a service, a program that stays on and answers requests, or a scheduled job, which starts at set times, does one task and stops. c-ads-watch runs on Railway. Cloudflare Pages serves websites made of files. This site is built into a folder of pages, and Pages sends them to each visitor. Both are downstream: they run finished work, not work in progress. Keys for a Railway job live in its variables, a settings page, so the code never contains them.

Crank practice A Railway job can gather data and feed a draft, but nothing it makes reaches a client without Peter. Its keys live in Railway’s variables, never in a skill.

Railway

External

What it is: A service that runs code on its own computers: programs that stay on, and jobs that run on a schedule.
Use it for: Anything that must keep running, or run at set times, such as c-ads-watch.
Not for: Being the only record, or sending to a client. What a job finds goes into git as a receipt, and anything for a client waits for Peter.
Where its work ends up: For the ads digest, its results feed a brief and a receipt goes into vault-c-peter (Flow 3).

Worth knowing: Railway’s schedules are in UTC. A job set for 06:00 UTC runs at 07:00 UK time until the clocks go back on 25 October 2026, then at 06:00.

Cloudflare Pages

External

What it is: Cloudflare’s service for websites made of files, sent to visitors from its network around the world.
Use it for: Static sites such as this one, crank-experiments.pages.dev: pages that are built once, then read.
Not for: Unmerged client work, unless access is limited. Preview links are public by default.
Where its work ends up: At the live address. The source stays in its Origin repo, and the built folder is made fresh on every build.

Seen 7 Oct 2026: the live site serves techniques 41 to 44, which only PR #1’s draft branch has, and a made-up address answers 200 with the hub. How main reaches Pages isn’t written down.

From the docs: Railway’s docs (scheduled jobs and variables), Cloudflare’s docs (Pages and Workers Builds) and GOV.UK (the clock change).

Go deeper: the external side

Railway’s docs say a scheduled job, which Railway calls a cron job, should terminate as soon as that task is finished. If the last run is still going, the next one is skipped. Start times can vary by a few minutes. A program that never exits, such as a web server, should run as a normal service instead.
Schedules are in UTC (Note that schedules are based on UTC), so You will need to account for timezone offsets. UK clocks go back one hour on 25 October 2026. A job meant for 7am UK time needs 06:00 UTC until then, and 07:00 UTC after.
On Railway, Variables provide a way to manage configuration and secrets across services. The code reads them as environment variables when it runs.
Pages and Origin: Pages’ Git integration connects to GitHub and GitLab, not Origin. Uploading built files instead, called Direct Upload, works from any computer, for example with Cloudflare’s Wrangler tool. But Cloudflare warns: If you choose Direct Upload, you cannot switch to Git integration later. Cloudflare’s Workers Builds does connect to Origin, with preview links and check runs on PRs, but moving the site to it would change the stack, so it’s only an option.
Branch previews: each upload for a branch gets its own address, plus an alias named after the branch. By default, these deployment URLs are public. An access policy limits them to Crank’s Cloudflare account.

↑ Back to the overview

Part W · two questions

Which place for which job? · when to use what

Rules of thumb: who does the work, and where it goes when it’s done.

W1 · Who does the work? Ask in order. Code changes go to a cloud agent, previews and experiments can go to the Mac mini, and most other agent work happens on the box.

W2 · Where does it go when it’s done? Each question stands alone, so one piece of work can get several yeses: a page lasts in git and runs on Pages.

Two questions settle most choices. First, who does the work? A change to a repo’s code goes to a cloud agent, because each one gets its own computer and branch and ends with a draft PR. A private preview, or an experiment, can go to the Mac mini. Most other agent work happens on the box. Second, where does it go when it’s done? Anything that must last goes into git. Code that must stay on, or run at set times, goes to Railway. Pages people read go to Cloudflare Pages. Anything for a client goes to Peter as a draft. These are rules of thumb, not a complete list.

Every place on this page, at a glance. These are rules of thumb.
Place	Side	Good for	Not for
The box	Local	Agent work in a browser or desktop app; running `crank-tools`	Keeping the only copy of anything
Cursor cloud agents	Local	Editing a repo’s code, as a draft PR on Origin	Merging their own PR
The Mac mini	Local	Private previews over Tailscale; experiments	Day-to-day Crank ads
Git: Origin repos and `vault-c-peter`	The record	Anything that must last: code, notes, receipts	Secrets: no key goes in a commit
Railway	External	Services that stay on; scheduled jobs, e.g. `c-ads-watch`	Sending anything to a client
Cloudflare Pages	External	Static sites, e.g. this one	Unmerged client work, unless access is limited

↑ Back to the overview

Part F · four examples

What does it look like end to end? · example flows

Four flows from start to finish. They’re examples, not a record of how every job runs.

Each flow runs top to bottom, and each step’s label says where it happens. The colours match the rest of the page: blue for the local side, green for git, yellow for the external side, white for a person and grey for the rest. A dashed box is optional.

Example Flow 1 · An educational page

Flow 1 · An educational page, like this one. A cloud agent builds the page and opens a draft PR on Origin. The Mac mini can serve a private preview first, and the solid line on the right skips it. A person merges, and Cloudflare Pages serves the page. How a merge reaches Pages isn’t written down yet (X2).

Example Flow 2 · A check with one right answer

Flow 2 · A check with one right answer. The skill doesn’t explain how to check. It names one shared command, so agents on the box and in the cloud get the same pass or fail. The model judges what to do next. The map names crank film check as one of the first commands in crank-tools.

Example Flow 3 · The ads morning digest

Flow 3 · The ads morning digest. A Railway job runs on a schedule, and Watcher turns its data into a brief. A receipt goes into vault-c-peter, and a draft Slack message waits for Peter. Nothing sends itself. Where Watcher runs isn’t covered here.

Example Flow 4 · UI verify

Flow 4 · Verifying a UI, once the first product exists. pstack’s /create-verification-skill writes the product’s verification skill and Feature Map, and agents put proof on draft PRs. /maintain-verification-skill keeps both current. This flow starts when the first product exists.

Crank practice Whenever a flow changes a repo or sends a message, a person makes the call. Agents open drafts, jobs prepare drafts, and a person merges or sends. For UI products, Flow 4 is the official verify path: /create-verification-skill, then /maintain-verification-skill. The map’s Pillar C explains the Feature Map and the drive loop.

↑ Back to the overview

Part R · four rules

What holds everywhere? · the rules

Four rules that apply in every place on this page.

R1 · Four rules, as do and never. They hold on every machine and service on this page.

R2 · Where a secret lives. The skill only names the key. The value stays in the settings of the place that runs the job, and the job reads it when it runs. The preflight check (gap 5) isn’t built yet.

Four rules hold in every place on this page, from the box to Railway. They’re Crank practice: decisions Peter and Cal have locked. Durable truth means whatever must last lives in git. Draft, not merge means a person merges every PR. No send without Peter means agents and jobs only draft what goes to a client. Secrets out of skills means a skill names a key but never holds it. R2 shows where the key lives instead.

Crank practice All four rules are Crank’s own. The Verification Gaps page lists checks that could back them up, such as the env preflight (gap 5) for secrets.

Rule 1: Durable truth in git

Crank practice

Why: The box, a cloud agent’s computer and the Mac mini can all be wiped, rebuilt or switched off. Git keeps every version, and every agent and person can read it.
In practice: Code goes to Origin as a draft PR. Notes and receipts go into vault-c-peter. If it’s only on one machine, it’s scratch.

Rule 2: Draft, not merge

Crank practice

Why: Proof makes a review faster, but a person still decides what becomes part of the main code.
In practice: Agents open PRs as drafts, and a person merges every PR. Nothing merges on a timer, however strong the proof or long the wait.

Rule 3: No send without Peter

Crank practice

Why: A message to a client can’t be unsent. Peter reads it first.
In practice: Agents and jobs can draft an email or a Slack message. Only Peter sends anything to a client (Flow 3).

Rule 4: Secrets out of skills

Crank practice

Why: Skills are plain text that many agents load, and they often live in git, which keeps every old version. A key written there can’t be taken back.
In practice: A skill names the key a job needs. The value lives in the settings of the place that runs the job, such as Cursor’s secrets or Railway’s variables (R2).

↑ Back to the overview

Glossary

Every term on the page, A to Z. The tag shows which part it belongs to.

Part LBox Crank practice: One shared Linux computer for Crank’s Grok Bot agents, with a desktop and browser for each agent.
BasicsBranch: A separate line of work in a repo. Changes on a branch don’t touch the main code until they’re merged.
Part Xc-ads-watch Crank practice: A Crank service that runs on Railway, named here as an example of a program that stays on.
Part LCloud agent: A coding agent running on its own computer in the cloud rather than on your laptop, so many can work at once.
Part XCloudflare Pages: Cloudflare’s service for websites made of files. It serves this site.
BasicsCommit: A saved change in git, with a note saying what changed and who made it.
Basicscrank-tools Crank practice: Crank’s shared toolbox of commands, so agents on the box and in the cloud run the same checks.
Part XDeploy: Putting a new version live, so people see it.
BasicsDraft PR Crank practice: A PR marked “not ready yet”. At Crank, agents’ PRs stay drafts until a person merges them.
Part FDrive loop: The steps a verify tool runs: start the app, check it’s healthy, use it the way a person would, save the proof and clean up.
Part RDurable truth Crank practice: Anything that must outlast the machine it was made on. At Crank it lives in git.
Part REnvironment variable: A named setting a program reads when it starts, such as which account to use. Secret keys are often passed this way.
Part XExternal: Downstream: the services where finished work runs for people. Here, Railway and Cloudflare Pages.
Part FFeature Map: Short notes, one per feature: what it does, how a user reaches it, how to drive it and what usually goes wrong.
BasicsGit: The system that records every change to a set of files, so nothing is lost and any change can be undone.
Part LGrok Bot: xAI’s agent product. The agents on the box run on it.
Part LLocal: The working side: the places where Crank’s agents make things. Here, the box, cloud agents and the Mac mini.
Part LMac mini Crank practice: A small Apple desktop computer. Crank’s works at home as a helper for previews and experiments.
BasicsMerge: Accepting a PR, so its change becomes part of the main code.
Part LOrigin: Cursor’s git hosting, where Crank’s code repos and their PRs live.
BasicsPR (pull request): A proposed change that waits to be reviewed and merged.
Part RPreflight: A check before a job starts that its keys are there and the right shape, without reading them. Not built yet: gap 5.
Part LPreview: A working copy of an unmerged change that you can open in a browser before it merges.
Part Fpstack: @poteto’s public set of skills for rigorous agent work, including /create-verification-skill and /maintain-verification-skill.
Part XRailway: A service that runs code on its own computers: programs that stay on, and jobs that run on a schedule.
Part FReceipt: A record, saved in git, that a job ran and what it produced, so anyone can check later.
BasicsRepo: Short for repository: every file in a project, kept in git so every change is tracked.
Part XScheduled job: Code that starts at set times, does one task and stops. Railway calls these cron jobs.
Part RScratch: Work that lives on only one machine. Useful while working, but not the record: if it matters, commit it.
Part RSecret: A key or password that gives access to something. It never goes in a skill, a log, a commit or a chat.
Part XService: A program that stays on and answers requests, like a web server.
BasicsSkill: A step-by-step procedure written in plain text that an agent loads when a task needs it.
Part LSnapshot: A saved copy of a cloud agent’s computer, so it can start again without setting up from scratch. Cursor deletes one after 90 days unused.
Part XStatic site: A website made of files that are built once and then sent as they are to each visitor.
Part LTailscale: A private network that links chosen devices, called a tailnet. Tailscale Serve shares a page inside it. Tailscale Funnel puts it on the public internet.
Part XUTC: The world’s reference time. UK time is one hour ahead of UTC in summer and the same in winter.
Part Fvault-c-peter Crank practice: The git repo that holds Crank’s durable notes and receipts.
Part LVM (virtual machine): A computer made of software, running on someone else’s hardware. Each cloud agent gets one.
Part FWatcher Crank practice: The step in the ads digest that turns the job’s data into a brief. Where it runs isn’t covered here.

Crank practice

Working decisions Peter and Cal have locked for Crank, and where each shows up on this page. These are Crank’s choices, not public teaching.

Durable truth lives in git. Code goes to Origin, and notes and receipts go to vault-c-peter. Anything only on the box, a cloud agent’s computer or the Mac mini is scratch (L2, rule 1).
Draft, not merge. Agents open PRs as drafts. A person merges every PR, and nothing merges on a timer, however strong the proof (rule 2).
No client send without Peter. Agents and jobs can draft an email or a Slack message. Only Peter sends anything to a client (Flow 3, rule 3).
Secrets stay out of skills. A skill can name the key a job needs. The value lives in the settings of the place that runs the job, never in a skill, a log, a commit or a chat (R2, rule 4).
Code changes go through Origin PRs. Cloud agents change a repo’s code on a branch and open a draft PR on Origin (Flow 1).
One shared toolbox. A check every agent needs goes in crank-tools, so box agents and cloud agents run the same command and get the same answer (Flow 2).
The Mac mini is a home worker. It’s for previews, experiments and outbox copies, not day-to-day Crank ads.
One official verify path for UI. pstack’s /create-verification-skill writes a product repo’s verification skill and Feature Map, and /maintain-verification-skill keeps them current (Flow 4).

Sources and credits

The places, the flows and the rules are Crank’s own, from Peter’s brief. Platform behaviour comes from the providers’ docs, and quotes are copied from them. Anything marked “seen” was checked live on 7 October 2026.

Crank practice, the places and the flows: Peter’s brief for this page, covering the five places, the four example flows and the four rules.
Companion pages: the Agent Engineering Map (Pillar B on crank-tools, Pillar C on Feature Maps and the drive loop, Pillar E on draft PRs, and its glossary) and Verification Gaps (gap 5, the env preflight).
Live checks, 7 October 2026, run by the agent that built this page:
- crank-experiments.pages.dev serves techniques 1 to 44, including #41 “Bot Jelly” and #44 “Curious bot”. No commit on main has technique 41. Only PR #1’s branch (cursor/grokbot-demo-media-aa0b, still a draft) has techniques 41 to 44.
- A made-up address, and this page’s address before it’s deployed, answer status 200 with the hub page.
Cursor docs:
- Cloud agents: run in isolated VMs in the cloud with full development environments instead of on your local machine; You can run as many agents as you want in parallel; They can also use computers to control the desktop and browser.; Cloud agents produce merge-ready PRs with artifacts; Secrets are injected when an agent starts.
- Cloud environment setup: secrets added in Cursor’s dashboard are exposed to the cloud agent as environment variables.
- Secrets and network: snapshots are Encrypted point-in-time copies of the virtual machine disk, stored for up to 90 days of inactivity.
Railway docs:
- Cron jobs: jobs should terminate as soon as that task is finished; Note that schedules are based on UTC; times can vary by a few minutes; not for long-running processes that don’t exit, such as a web server.
- Variables: Variables provide a way to manage configuration and secrets across services in Railway.
Cloudflare docs:
- Serving Pages: with no top-level 404.html, Pages treats a site as a single-page app and sends the home page for unknown addresses.
- Preview deployments: By default, these deployment URLs are public.
- Pages Git integration: connects GitHub and GitLab repositories.
- Direct Upload: If you choose Direct Upload, you cannot switch to Git integration later.
- Workers Builds: Cursor Origin integration: posts preview URLs in PR comments and creates check runs.
Tailscale docs: Tailscale Serve, which lets you route traffic from other devices on your Tailscale network (known as a tailnet) to a local service running on your device; If you’d like to share local services publicly over the internet, use Tailscale Funnel instead.
GOV.UK: When do the clocks change? British Summer Time ends on 25 October 2026, when clocks go back one hour.
pstack, by @poteto: the pstack plugin and its /create-verification-skill and /maintain-verification-skill skills.

How this page was made

Model: Claude Opus 5.5 at max effort (claude-opus-5-5-max, from this run’s metadata), in one Cursor cloud agent run with no subagents.

Token total: missing. The run metadata available to the agent doesn’t report a token count, so no total is shown and none was estimated.

Built 7 October 2026 from Peter’s brief, in the same run as the Verification Gaps page. Build note: src/e/crank-architecture/BUILD-NOTE.md.