A platform for agents that are files
Agents are just markdown.
Write an agent as a folder: its role, its tools, its knowledge, its memory. Write a flow as a numbered list. Push the folder and it runs without you — on a schedule, in a sandbox, with a budget, behind a gate a person decides.
$ npm install -g foldrun
$ foldrun init my-desk # a workspace that already runs
$ foldrun check # no model is called
$ foldrun run publish
Nothing above needs an account. The CLI is Apache-2.0 on npm.
---
name: rival-watcher
description: Reads the result pages for the money terms and
says who is above us and what they are doing that we are not.
model: default
tools: [read, serp_check]
secrets: [DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD]
size: small
---
`serp_check` is billed per query. Read five to eight, chosen
from what group 1 produced, and say why you picked each.
For every query: who is above us, in order, with their URL.
What kind of page is winning — a directory, a rival's service
page, a government page. What sits above the organic results:
if an AI Overview is answering, say so loudly, because
"rank higher" is the wrong instruction there.In production today: a search-marketing department of seven desks — 60 agents, 11 flows, 46 tools, one person approving — running a national building-inspection company's organic presence, every week, on foldrun.
Three verbs. No build step.
The files are the program. There is nothing to compile, no SDK to import and no pipeline to define — the loop is edit, check, run, deploy, and every one of those is a command you already know.
01
Write
An agent is a folder with an agent.md: frontmatter grants, prose is the prompt. A flow is a numbered list. Same number, same time; a ! parks it for a person.
agents/reporter/agent.md
flows/rankings.md02
Check
foldrun check validates the whole workspace offline — a step naming an agent that does not exist, a tool that resolves to nothing — before any model is called. Run it like a typecheck.
$ foldrun check
✓ 6 agents · 1 flow · 4 tools — no problems03
Run
Locally against your own key, or push the folder and it runs on a schedule with its secrets in a vault, its steps in sandboxes, and one line at the top saying what happened.
$ foldrun run rankings
BAD — 3 targets fell out of the top 20 this week …A flow is a numbered list.
Steps run in order. Steps that share a number run at the same time, and the next group is handed everything they said. A !parks the run for a person. A verify:is where arithmetic goes.
The model decides what to do inside its step. The file decides what happens after it. There is no free-form handoff between agents, because that is where systems loop.
- → Routing with
case:, fan-out witheach:, a critic loop withloop:+until: - → Compose a whole flow as a step:
[[flow:weekly]] - → Consult a colleague inline, or let the model delegate from a list you wrote
---
name: rankings
trigger: schedule
schedule: "0 5 * * 3"
timezone: Australia/Sydney
budget: 5
---
1. [[position-tracker]] — the full ranked-keyword set
1. [[page-match]] — queries where the wrong page of ours ranks
1. [[target-tracker]] — every target, measured where the searcher is
2. [[rival-watcher]] — read the result pages for the money terms
2. [[local-serp]] — check the money terms city by city
3. [[reporter]] — rank the week's work; open with the verdict
verify: matches: ^(GOOD|BAD|QUIET|BLOCKED)\bThe platform underneath.
Everything a scheduled agent needs to be trusted with real work, and nothing that has to be configured before it does something.
A sandbox per step
Every step runs in its own container — a gVisor pod on a cluster — with a copy of the agent's folder and nothing else. Under a second to start. Gone when the step ends.
Gates a person decides
Mark a step with ! and the run parks until someone approves — from the dashboard, the emailed link, or an external event. The decision and its note are on the record.
Budgets at three levels
A cap per run, per workspace per month, per account per month. The run that crosses its cap fails between groups and the notification says why. No timeouts otherwise: the file is the only clock.
Schedules and triggers
Cron with a timezone, a webhook, an inbox, another flow finishing, a file landing, a URL changing. Overlap policy per flow.
Memory that survives deploys
Knowledge is what you tell an agent; memory is what it learned; state is the bookmark between runs. A deploy replaces the source and never touches what was learned.
Git is the deploy
Every workspace is a git remote. Push main and it is live with its evals run; push a branch and you get a preview that never fires a schedule. Rollback is a new commit.
Secrets that stay secret
Named in the agent's file, handed to its scripts as environment variables, never in a prompt, never in git. Per-account encryption keys, wrapped by a root key no backup holds.
A record you can read
Each run keeps every step's reply, tool calls with timing, cost and tokens, and a timeline. The first line of the last step is the headline — in the run list and in your inbox.
QUIET — all 119 articles in this slice are indexed; Bing added 18 URLs over 14 days.
index-desk · indexing · completed · $0.81
BAD — 3 tracked targets fell out of the top 20 this week, most notably insurance claim assessment, now held by two insurers.
rank-desk · rankings · completed · $1.01
Apply these fix links to the live site? The brief is at storage/fix-proposal.md. Reply GO, or name the addresses to keep.
link-desk · fix · awaiting your approval
Built for the person who approves.
Agents work; people supervise. So the thing a person sees first is not a log — it is one line saying what happened, written as the subject of an email. The run list is a status board. The inbox is a status board. A parked run finds you; you do not go looking for it.
Seats are unlimited. A platform that charged per supervisor would be taxing the one thing that makes autonomous work safe.
Isolation you can explain.
The security model →One step, one sandbox. A container on a box, a gVisor pod on a cluster. It holds a copy of the agent's folder and nothing else, and it is destroyed when the step ends.
The public internet, and only that. Every private network range and the cloud metadata endpoint are denied to a run. So is the platform's own API.
Capability is a grant, not an instruction. An agent with no tool that writes cannot write, whatever it is told or tricked into.
Everything is on the record. Every step's tool calls, every refusal, every decision at a gate and who made it. A run can be reconstructed from its record.
Push the folder. It runs without you.
Start locally today — it needs nothing but a model key. When it is worth running on a schedule with a team, the same folder deploys to the cloud with one command.