Swarm Overview
Let work branch across delegated agents while a signed task graph bounds its depth, fan-out, budget, and every child's authority.
On this page
Delegation that can recurse can also multiply authority, unless something outside the delegators holds the shape of the work. In a swarm, a signed task graph holds it: the graph fixes how deep delegation may go and how wide each task may fan out, every child holds less than its parent, and allocations drawn from one budget pool never sum past it. A planner can divide its work and cannot widen the graph it was given.
a1task-child-aa2task-child-ba3task-child-c
One signed graph bounds how far work can branch
task-root delegates to three depth-1 children. The graph signs maxDepth 2 and maxFanout 3, so every node stays at or below depth 2, each edge advances one level, and no parent has more than three children. The results meet at join-child-results, whose next task is task-root; a join adds no delegation edge. Task Graphs.
Each child needs a valid delegation path, a bounded allocation, an admitted route, and a current continuation, and the kernel checks all four even when another operator runs the child. Results converge at a join, and the terminal graph receipt reconciles the declared budget rollup.
A signed graph holds the shape of delegated work
task-root delegates to three depth-1 children under a signed maxDepth of 2 and maxFanout of 3, and their results meet at join-child-results, which adds no delegation edge. The pool holds 10,000 usd_minor units and each child 2,500, leaving 2,500 unallocated; the verifier checks that the ceilings sum to at most the pool. The terminal graph receipt lists all four tasks, the join, and the three route plans, and its rollup of 7,500 active units must equal the allocations.
From the Computer facade, a grant's delegation: { depth: 2, fanout: 4 } sets the allowance and authority.delegate issues each narrower child. The kernel admits swarms deeper than one level within those limits on the serving path and refuses them beyond. Federation supplies the standing relationship when a child runs on another operator's kernel; graph authority binds the delegated work that uses it.
Read more in Task Graphs and Graph Verification.
Two delegated workers each hold one tool and one call
A coordinator gives one worker permission to count a document's words and another permission to count its lines. The two workers run concurrently, and the coordinator combines their results into a report. The fixer uses the same shape when it hands the tester one test run and the reviewer one diff on issue #417.
Install Rust and the platform build tools from Installation, then download and extract the complete Rust application. Its runtime helper is bundled, and Cargo fetches the pinned public Chio dependencies.
cd delegated-agent
cargo run --release --locked -- sample.mdword-worker: ALLOW {"words":9}
line-worker: ALLOW {"lines":2}
report: {"document":"sample.md","lines":2,"words":9}
cross-tool: DENY requested tool count_lines on server text is not in capability scope
exhausted-worker: DENY invocation budget exhausted for capability worker-fffc67ff-9ced-48d5-a06f-a8fcfb488fea
widened delegation: REFUSED attenuation violation: child scope is not a subset of parent scope
evidence: runs/31ed8211-7b17-4c4a-aee2-7da4ba4115c3The included sample.md has nine words and two lines; pass any UTF-8 document instead. After the report, the run exercises three boundaries:
- Cross-tool. The word worker's capability asks for line counting, outside its scope.
- Exhausted. A second word count exceeds the worker's one-call limit.
- Widened. The coordinator asks for a larger limit than the parent allows, and the delegation API refuses before any child token is issued.
The word worker's grant and how it was issued
The grant names the application's text server, permits only count_words, and bounds the call count. The coordinator calls delegate with explicit attenuation steps (remove the other tool, remove the delegate operation, reduce invocations to one, shorten the expiry), so the child expires within two minutes and carries the coordinator's signed delegation and a scope-subset witness. The host materializes the child capability and verifies its signature, and no worker receives either signing key.
{
"server_id": "text",
"tool_name": "count_words",
"operations": [
"invoke"
],
"max_invocations": 1
}Each mediated call, both denials included, has its own signed receipt in the printed run directory, beside report.json and the complete child token in count_words-capability.json. The widened delegation is an unsigned diagnostic, because it fails before any kernel call. Change the worker's operation in TextTools in src/host.rs, the coordinator's tools and limits in the root grants of host::boot, a worker's tool, quota, or lifetime in worker_capability in src/main.rs, and the combined result after tokio::try_join! dispatches both calls.
The workers are deterministic and local. Keys and budget counters start fresh with each process while SQLite retains the run's lineage and receipts. Each child receives half of the registered parent allocation and its own one-call quota, which sets no monetary budget and no family-wide invocation ceiling.
Use a graph when the shape of the delegation must be checked
An ordinary capability is enough to give a worker one tool, and an ordered workflow fits a fixed sequence your host owns. A native agent process is the durable identity and lifecycle of one worker, and a process host can supervise children and retain mailboxes without a signed graph. Graph authority preserves the signed relationship between branching tasks, their allocations, continuations, routes, and joins. Agent count and deployment size do not decide the choice, and a cluster, which coordinates an operator's control state, is a separate concern.
Every Swarm page, from the graph to its evidence
- The Delegation Graph. Swarm Authority traces every child's authority to a signed plan, Task Graphs bounds depth and fan-out, and Delegation Witnesses proves each hand-off narrowed scope.
- Fan-Out & Fan-In. Sub-Agent Budgets divides one ceiling, Continuation Tokens binds a child to its plan, Route Plans pins its route, Revocation Epochs withdraws a subject or task, and Join & Terminal Receipts checks that the graph closed as declared.
- Joint Authorization. Bilateral Co-Sign signs one invocation with two operators' keys, FROST Quorum requires a threshold of signers, and Governance Ladder folds both operators' manifests into one contract.
- Coordination Signals. Signals between agents ranks work by decayed, receiver-weighted strength and grants nothing, Reputation & Scarcity bounds tasks and deposits, and Delegation Hygiene scores the restrictions a delegator added.
- Cross-Agent Disclosure. Selective Disclosure opens only the fields a recipient needs, and Disclosure Lineage checks disclosed evidence against its provenance graph.
- Operations & Walkthrough. Graph Verification admits and revalidates a child's bundle, Relay Operations delivers signal batches between operators, Swarm Denial Codes names each refusal and its repair, and the 3-Vendor Walkthrough lets an auditor check every handoff offline.
Every swarm chapter builds from one Rust project
The chapters run graph construction, admission, joint signatures, disclosure, reputation, and relay delivery from one download. The project selects Rust 1.94.1 and fetches its Chio dependencies from an immutable public Git revision, so no source checkout is needed beside it.
curl -fLO https://www.chio.computer/examples/swarm-authority.zip
unzip swarm-authority.zip
cd swarm-authority
cargo run --locked --bin authorityThe authority program writes a signed bundle, prints the public key and evaluation time that verify it, and checks that verification with no pinned signer refuses, as its captured result shows. Each chapter names its executable and any optional feature; start with constructing a graph, installing admission on a kernel, or collecting joint signatures. The project README lists every command and the boundary each one exercises.