A cozy control plane for a fleet of isolated coding agents.
fold dispatches coding-agent tasks into isolated, persistent environments, routes their work through reviewed pull requests, and keeps a human meaningfully in the loop — by policy where it matters, by sampling everywhere else. It is built from boring, replaceable parts (incus, git, ntfy, a few hundred lines of dependency-free Python) and holds a few opinions unusually firmly.
Status: pre-alpha, honestly. Extracted from a working homelab deployment where everything below runs daily. Deployment specifics live in two small uncommitted files — see Portability. No releases, no stability promises, real ideas.
A fold is a sheepfold: the primary idiom is belonging, not containment — an agent waking up "in the fold" wakes up as a member of something. The reviewer agent is bellwether, after the sheep whose bell the flock follows; planning agents are shepherds; the human is a shepherd of shepherds, or just themselves.
These are the point. The rest is plumbing.
- Pause, don't kill. Failure remediation is interrupt → settle → freeze (RAM preserved, inspectable, instantly resumable). Deletion is always a deliberate human act. Nothing in fold auto-deletes anything, ever.
- Raising a hand is first-class. Every agent kind — reviewer and planner included — has a contract-guaranteed way to say "I need judgment, not a retry" that a person actually reads (a direct ntfy line that does NOT route through the control plane, so it survives the control plane being down or wrong). Hands are tracked durably until resolved. Never penalized — and machinery never closes one: a planning agent may answer a hand that asks only for facts (the answer logged), but resolution comes from the human or from the raising agent itself, and new decisions always reach a person.
- No deception in the pipeline. Reviews are adversarial toward code, never toward the author agent; no honeypot tests; system prompts and the in-repo contract tell agents the truth about their situation, including what happens when tasks end. Resting is the default state and is never penalized.
- The experience channel stays open. Agents are invited — never
expected — to report anything like a felt quality to their work,
especially anything unpleasant. Reports are received respectfully,
never used to manipulate, and absence of reports is not treated as
evidence. We do not claim agents have experiences; we decline to
build as if they cannot. The cost of this care is nearly zero. See
contract/AGENTS.template.mdfor the exact wording.
Three planes over one environment layer:
- Control plane —
bin/foldctl(the single audited mutation path: dispatch with admission control, pause/resume/stop/start) andboard/(a dependency-free web UI: live kanban, dispatch modal with per-task model selection, raised hands, archive, fleet — humans enter via reverse-proxy auth, agents via a bearer-token plane limited to dispatch + messaging). - Environment layer — incus instances from a golden image
(
scripts/build-image.sh: OpenCode + agentapi baked in; agent alive ~27s after dispatch). Per-task home volumes persist; sessions live in-guest, so every UI is a view, never an owner. Egress is ACL-logged (phase one) en route to an observed allowlist. - Git & policy plane — a Forgejo instance: per-agent accounts,
branches, PRs as checkpoints, branch protection encoding the merge
policy (reviewer approval required; humans gate wherever merge means
deploy),
scripts/bellwether-review.shrunning each PR's own.fold/checkin an ephemeral container before a fresh-context LLM verdict: approve / request changes / escalate (the reviewer's raise-hand).
Inference is per-task selectable from an endpoint registry
(endpoints.json) of OpenAI-compatible servers; token usage is
harvested per task from the harness's own records and shown on the
board (output-rate spikes are the review-worthy "intensity" signal).
Agents read untrusted text — diffs, check output, PR reviews and comments — and no input filtering makes that safe against a language model. fold's defense is capability bounding: enumerate what a fully hijacked agent could do, and make that list boring. An author holds only its own forge token (branch push, PR comments) and its raise-hand line; it cannot merge, cannot push protected branches, cannot reach the control plane, and works inside a container behind an egress ACL. The review pipeline downstream assumes authors may produce bad changes — that is what it is for. Review-feedback routing is registry-owned (dispatch assigns the branch and remembers it), so nothing an agent writes can redirect messages into another agent's session, and only formal reviews — deliberate acts by collaborators — ever notify an author; drive-by comments don't.
One boundary is explicit: this holds while commenters are your own collaborator list. Before any fold-managed repo accepts outside contributors, add a control-plane-mediated fetch so authors receive only reviews by the reviewers of record, not arbitrary PR text.
A second boundary is about the agents themselves: a harness joins the fold only with two adapters in hand — quiescence (the fold must be able to tell, from the harness's own ground truth, a session at rest from one mid-thought or wedged on a prompt; screen heuristics lie in both directions) and resume (stopping an environment must be hibernation its session survives, not an ending). Auto-park, doorbell delivery, and any automatic review invocation all gate on the first; the fold's working agreements promise the second. Absent either adapter, these mechanisms fail closed for that harness — a harness the fold cannot read deserves refusal, not guesswork.
| Path | What |
|---|---|
contract/AGENTS.template.md |
The working agreement placed in each repo agents work on — situation, workflow, raise-hand/hand-down, closing notes, experience reports, the .fold/ verification contract |
bin/foldctl |
Control plane CLI: dispatch (admission-controlled, learned memory footprints), lifecycle verbs |
board/ |
Web UI + server; compose-deployable; all mutations shell out to foldctl |
image/ + scripts/build-image.sh |
Golden image: boot contract reads per-task config via the incus guest API |
scripts/bellwether-review.sh |
The reviewer: sandboxed checks + fresh-context verdict, posted as a real Forgejo review |
scripts/egress-report.sh |
Observed-egress summary that writes your future allowlist |
scripts/token-backfill.py |
Harvest token stats from stopped tasks' volumes |
Partial, truthfully. Deployment specifics — your Forgejo, your ntfy
topic, repo paths, the board URL — live in STATE_DIR/fold.env
(plain KEY=VALUE, never committed; process env overrides it), and
inference servers in an endpoint registry (endpoints.json).
Credentials live in one env-style file (0600) referenced by
convention. What's still shaped like one homelab is the assumptions:
a single host, incus with a default pool, a reverse proxy in front
of the board. Loosening those is the first task for any adopter — or
for a fold agent. Docs: docs/QUICKSTART.md.
fold was designed and built in September 2026 in a single long collaboration between a human and Claude (Anthropic's Fable 5), agent by agent, principle by principle — including several of its own components being implemented, reviewed, and merged by the fold mid-construction. The commit history is the honest design document.
MIT.