Start here
Your account
Operating it
Agents are folders and flows are numbered lists, so there is no build step: edit, check, run, deploy. Start on your own machine — none of it needs an account.
npm install -g foldrun
foldrun init my-workspace # a workspace that already runs
foldrun check # validate everything — no model is called
foldrun run publish # run it, locally, for realWhat foldrun is, and from nothing to an agent running on your own machine.
foldrun is a platform for running agents that are written as folders of markdown. An agent is a folder with an agent.md in it; a flow is a numbered list of steps; a tool is a file that says what may…
An agent is a folder. A flow is a numbered list. There is no build step — the files are the program — so the loop is edit, check, run, deploy.
Eight nouns, one reference syntax, and a flow that is a numbered list. Nothing here is a framework you import — every one of these is a markdown file you can open, diff and review.
Every field, on every kind of file. What a workspace, an agent, a flow, a tool and an eval accept, and what each one does.
A workspace is a folder, and the folder is the unit of everything: it is what you edit, deploy, permission, budget and back up. An account holds several — one per job, in practice — and they share…
agents/<name>/agent.md is the only required file an agent has. Frontmatter for the machine, body for the model — and the body is the prompt, so write it as instructions to a colleague rather than as…
A flow is a numbered list of steps in a markdown file under flows/. Steps run in ascending group order, and each receives the results of every earlier group, oldest first — a group-3 reporter sees…
A tool is one markdown file describing something an agent may call. One noun for capability: transport: says how it connects, and an agent grants it by name in tools:.
An eval is a markdown file under evals/ that runs an agent or a flow against a task and asserts something about the reply. It is how a change to a prompt stops being a guess.
Four places hold what an agent knows, and they differ only by who may write. Getting the four right is most of what separates a desk that improves from one that repeats itself.
What happens once it runs: schedules, the run record, approvals, what it costs, where the files go, and who gets told.
A flow starts when its trigger fires. The default is a person — a button, an API call, foldrun invoke — and everything else is a line in the flow's frontmatter.
A run is the record of a flow being driven from its first step to its last: every step's reply, every tool call, every cost, and one line at the top that says what happened. It is the unit of the…
Money on this platform is a cap at three levels and a meter underneath. The caps are yours to set and the thing to set first: an agent with a tool loop and no ceiling can spend in an hour what a…
Two kinds of file live in a workspace, and the dashboard shows them on two pages. Files is the markdown source — agents, flows, tools, knowledge — the thing you edit and deploy. Storage is bytes:…
An agent that runs while the laptop is closed needs a way to say "I finished", "I failed", and above all "I am waiting for you". A run parked at an approval nobody hears about is a run that never…
A secret is a value an agent may use and must never see written down. It is stored in the platform's vault, named in an agent's secrets: list, and handed to that agent's scripts as an environment…
People, roles, keys, and getting a workspace onto the platform.
Every member and every API key has a role, and every write route asks for the least role that may take that action. Reads are open to every role: a viewer sees everything, including run output and…
A workspace deploys by pushing files. Two doors, one mechanism: foldrun deploy from a folder, or git push to the remote every workspace has. Both are checked before anything goes live, both refuse to…
What provider: { name: … } resolves to. Generated from packages/core/src/providers.ts and checked against each provider's own documentation on 2026-09-02; the table below is what the runtime…
Running the platform yourself, what it does and does not let an agent do, and when something goes wrong.
The platform runs in three shapes, and the same workspace moves between them unchanged. Pick by who the install is for.
The platform runs code it did not write, on behalf of people who may be wrong about what it will do, next to other people's data. Everything in its design follows from taking that seriously. This…
The failures people actually hit, what the platform is telling you, and the fix. Every one of these leaves its reason in the run's events; read those before anything else.
Is this a framework? No. There is nothing to import. An agent is a folder, a flow is a numbered list in a markdown file, and the CLI or the platform reads them. You can write a working workspace in…
Every command, every route, every variable. The things you look up rather than read.
foldrun needs no account. ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN) is enough to run agents; init and check need nothing at all.
Every route under /api. Generated by hand from the handlers and kept honest by tests/consistency.test.ts, which fails the build if a route exists and this file does not mention it.
Everything a self-hosted install reads from its environment. Unset means the default in the right-hand column; a blank default means the feature is off.
account — the top level: people, keys, the library, the wallet, and the workspaces under it. Has one owner.
Decision records. Written when the decision was made, so they say what was actually traded rather than what sounds good afterwards.
Written 2026-08-29, after counting. This is a limit, not a plan — it says what the format will NOT grow, and why the pressure to grow it will feel reasonable every single time.
Written 2026-08-29. Sequels scaling-adr, which said when to move state off files. This says what moves, where, and in what order — and names the two things that are not a storage problem at all.
Written 2026-08-27, while the design was fresh. This is the plan we execute WHEN a trigger fires — not before.