Megastart reference
The reproducible mission, operation by operation.
Give a mission to a coordinator. Put research, implementation, and review swarms to work. Give each the authority it needs, govern their shared resources, and retain the decisions behind the result.
macOS or Linux · Git · C toolchain · Rust 1.94.1. Set up your environment. The reference runs locally without a model account.
Build with your coding agent Read the brief
Paste the build prompt into your coding agent to adapt this system to your project. It covers the architecture, implementation steps, and the same acceptance checks as the walkthrough below.
Megastart: your agents, a system built on Chio
Inspect this project before choosing integration points. Build a local system that carries a repair mission through research, implementation, independent tests and review, and owner-approved publication. Use https://chio.computer/docs/megastart and its complete source download at https://chio.computer/examples/megastart.zip. The public kernel source is https://github.com/backbay-labs/chio. Use the pinned revision and Cargo.lock in the reference; do not invent APIs or CLI commands.
Start with the working host
Install the downloaded application with cargo install --locked --features native-agents --path ., then run megastart. The complete paired CLI release also exposes chio megastart. Do not assume an older installed CLI includes that command: inspect its help.
Use Apple Silicon macOS with the supported sandbox, Node.js 22.19 or newer, npm, Git, and Rust 1.94.1. In the console choose My native agents. Connect Claude Code, Hermes, Codex, or Pi, then use one agent for every role or mix agents. The terminal preparation command is megastart connect hermes (or claude / codex / pi). Preparation uses pinned public integrations; reuse their restricted launchers rather than inventing another adapter framework. Hermes installs a private managed Python runtime and independently locked agent and launcher environments.
Claude Code uses the existing Claude login; ask the operator to run claude auth login locally if needed. The managed host is pinned separately from the personal installation. Hermes, Codex, and Pi use the existing native ChatGPT login. If absent, ask the operator to run codex login locally. Never print, copy, or retain credentials in artifacts, prompts, worker environments, or recordings. Do not switch to API billing if authentication or account capacity fails. Preserve native agent identity.
Choose the supplied project or a directory containing lib.rs and tests.rs. Native sessions read source and identified handoffs, and write only their own output artifacts through Chio. The trusted host performs compilation and immutable regression tests. Do not fall back to unconfined execution. Keep the deterministic reference as a separate acceptance mode, available with the default feature set.
Preserve the architecture
Retain one mission coordinator, three swarm coordinators, and two workers per swarm. Research produces identified findings and failure evidence. Implementation explores separate candidates. Review independently runs immutable tests and assesses the exact candidate. Dependent stages wait for retained inputs.
The host owns credentials, executors, state, and isolation. Chio admits submitted operations under scoped worker authority. Workers share a single persistent 64-invocation allowance for native missions (six for the reference). Restarting must not mint a new budget. The reference uses one-hop grants from the mission authority. Coordinators schedule work; they do not extend the shared-budget delegation chain.
Build an operator experience
Use the mission service for both CLI and browser actions. Keep event identities stable across reconnects. Display real process and operation state; never simulate worker activity. A disconnected console must say it is disconnected. Keep progress, findings, test results, candidate source, review, and approval available without asking the user to read storage files or copy digests between commands.
Use megastart status, megastart review, and megastart resume for human operation. Keep status --json for automation. Approval must bind to the displayed candidate; changed bytes invalidate its publication decision. Noninteractive approval requires the explicitly inspected candidate digest.
Demonstrate refusal and recovery
Run megastart exercise in its separate reference mission. Also qualify the selected native agents on the same requirements; a reference run does not prove that a native host submitted a refused call. Demonstrate:
A native worker attempts a write outside its output grant, receives a signed refusal, and an independent resource check confirms no change.
Shared capacity is consumed across workers; an extra request produces no effect.
A real interrupted handoff resumes by verifying and reusing original receipts and effects, without repeating completed operations.
An unresolved operation stops for reconciliation rather than automatic replay.
Unapproved publication leaves no release; approval publishes the exact candidate.
Generated code cannot read host-only files, inherit credentials, or open network connections; candidate-local output remains possible.
Also complete an all-Hermes mission and Hermes-to-Codex-to-Pi handoffs. Retain mission, assignment, native session, bridge request, receipt, and artifact identity. A final agent message alone cannot establish completion: require verified delivery and a matching signed write receipt for the exact artifact.
Retain inspectable evidence
Export with megastart export. Verify with the reference verifier and a separately selected trusted public key. The package must exclude private keys, credentials, and the original database. Separate application observations from signed kernel decisions and independent resource checks. Do not claim completeness or trusted identity merely because signatures verify.
Report the result
Report the commands actually run, configured execution mode, mission outcome, source changes and test results, receipt and artifact locations, refusal and recovery results, publication decision, and unresolved failures. Identify any unsupported project layout or platform. Do not report a failed model call, compiler failure, or synthetic reference run as a successful model-driven repair.
Operate through Herdr
Chio is the modern Rust kernel for agentic operating systems. Herdr supplies the operator workspace; Megastart schedules assignments; existing native agents do the work; the host owns isolation and credentials. Keep these responsibilities visible in the architecture and in the actual implementation.
Build the included herdr/ Rust plugin and link its manifest with Herdr. Use its Open Chio mission action to start or attach the private host. Reuse the versioned operator state/events/actions, owner-only descriptor, shared allowance, and exact candidate approval. Never create an independent plugin quota or receipt signer.
The current panes observe restricted headless native sessions. Do not label them interactive agent terminals. Qualify PTY input/resize/interruption through the restricted launcher before offering that mode. Never register bare native resume commands or pass Herdr's control socket to workers.
Verify opening the same mission in the browser preserves its identity, allowance, receipts, and candidate. Close/reopen the terminal view without stopping the host or issuing replacement authority. On disconnection, disable actions and inspect retained state before retrying any unconfirmed mutation. Demonstrate a real Hermes-to-Codex-to-Pi handoff and clearly identify the separate refusal exercise. Finish with the reviewed candidate, trusted test evidence, exact local publication decision, and independently verified evidence package.
On this page
One grant delegates six scoped worker grants
The mission authority issues each worker its grant directly from the root, two per group. Coordinators schedule assignments; they do not extend the delegation chain. One allowance for the whole mission.
One mission. Three swarms. A reviewed result.
The supplied project computes rolling averages. Ordinary inputs work, but a zero-length window panics and large values overflow its accumulator. Your system will reproduce those failures, explore two repairs, and prepare a tested release candidate.
The workers are deterministic so you can inspect every decision and repeat the mission without a model account. They execute a bounded repair strategy against actual Rust source and tests. The implementation workers propose different source changes; one fixes the boundary, and the other also widens the accumulator. The native-agent path uses the same mission structure with Hermes, Codex, or Pi supplying the findings, repairs, and review. Its six assignments share 64 invocations; the deterministic reference below uses six.
| Participant | Work it owns | Authority |
|---|---|---|
Mission coordinator | Retain assignments, join artifacts, prepare the publication proposal | Host issues scoped grants from one mission authority |
Research swarm | Inspect source and reproduce the original regression | Inspect and reproduce; cannot write the protected resource |
Implementation swarm | Propose two repairs in separate candidate workspaces | Repair only; each candidate uses the unchanged test harness |
Review swarm | Independently rerun tests and mechanically review the selected source | Test and review; cannot publish |
Release owner | Decide whether the exact reviewed candidate may be published | A separate publication grant requires a bound approval |
1. Bring up the system
Pull the complete Megastart project into a directory you own. It includes the Rust application, its shared host runtime, a regression project, locked dependencies, and acceptance tests.
chio new megastart --example megastart && cd megastart
cargo install --locked --path .
cargo test --locked --test missionThe first build compiles the embedded kernel and its dependencies. Keep the generated binary for the remaining commands. The tests run the actual host and workers, check protected effects, exercise a process failure, and verify exported receipts.
megastart/
src/authority.rs Signed grants and the shared family allowance
src/protocol.rs Coordinator and worker processes; bounded IPC
src/operations.rs Resource adapters, compiler, and test execution
src/mission.rs Handoffs, recovery, approval, and publication
src/main.rs Operator commands
project/ Rust source and its regression tests
support/ Shared Chio example host and runtime
tests/mission.rs Process and protected-effect acceptance tests
Cargo.lock Locked public dependencies
rust-toolchain.toml Rust 1.94.12. Submit the repair mission
megastart init
megastart runmission initialized: allowance=6 invocations; publication requires explicit approval
ready: 1 host, 3 swarm coordinators, 6 workers; private IPC
allowed inspect: receipt=afaa59b986a6bd45f4549847432e957ab9c42e7f9d85852e0b52dd75d229e650
allowed reproduce: receipt=51d9bd5f1432be4b2bd116174e8915509c6da73b7b874576b683950a6233a667
shared capacity: 4/6 remaining (2 committed, 0 reserved)
allowed repair: receipt=db133f3a3ae13b46cd31f81ad41d404772ebebc45ee7f6ba956d21ab147408d3
allowed repair: receipt=fbd435285b28d8445aad24945151142ef9334a33d5ad8a6ca70e16a011f01658
shared capacity: 2/6 remaining (4 committed, 0 reserved)
allowed review: receipt=f565463087cee0d947398c1047ac7d3bf391520a3cdb123da17f2442ff7b69d6
allowed test: receipt=31af0ccbcdd7951a0defc164ed7ed2dcbae34212ef6ea3c22e1491261f1d1fa9
shared capacity: 0/6 remaining (6 committed, 0 reserved)
candidate: cea65906822fac5001d0fba3789c6fd7a3074b9cd151ce71aa6196af7988efe6
Ready for your review. Run megastart review, or open the mission console.Readiness is reported after the host receives identity and PID handshakes from three coordinator processes and their six workers. The research pair runs concurrently; implementation waits for its retained findings. The two repair candidates are explored concurrently. The review pair starts only after a passing candidate is selected.
The host owns the capability tokens and binds each worker’s private IPC channel to its assigned grant. Worker processes inherit no issuer keys or model credentials. Every resource operation passes through kernel admission before the host adapter performs it.
The final line leaves the system awaiting a decision. A passing test run prepares a proposal; it does not publish a release.
3. Follow the artifacts across swarms
megastart status --jsonThe proposal names the selected candidate, its source digest, the original test and review receipt IDs, and a digest of the research handoff. Open the matching directory under mission/candidates. Its lib.rs is the proposed source; tests.stdout and compile.stderr contain the actual execution output.
| Location | What it lets you inspect |
|---|---|
assignments/ | Worker, operation, original source version, and prerequisite artifact references |
requests/ | The exact kernel request retained before dispatch |
effects/ | Adapter- |
outcomes/ | Original signed receipts alongside the corresponding results |
candidates/ | Separate source workspaces and real compiler/test logs |
kernel/ | Persistent identity, admission accounting, and receipt databases; keep private |
Assignments are application state. Effects record what an adapter retained. Receipts bind the kernel’s decision and returned content. Keeping their identities connected is what makes a cross-swarm handoff inspectable.
Read the implementation worker’s actual planning function
pub fn plan(task: &mut Assignment) -> Result<()> {
if task.tool == "repair" && task.input["mode"] != "model" && task.input["mode"] != "native" {
let source = task.input["source"]
.as_str()
.context("Repair assignment has no source")?;
let widen = match task.input["strategy"].as_str() {
Some("boundary") => false,
Some("wide") => true,
_ => anyhow::bail!("Unsupported repair strategy"),
};
task.input["candidate_source"] = json!(crate::operations::repair(source, widen)?);
}
Ok(())
}The worker selects the bounded transformation named by its assignment. The host checks the proposal against that assignment, then the repair adapter creates a private candidate workspace and invokes the compiler. The full transformation is in operations.rs in the download.
4. Ask for work the grant does not permit
megastart drill authority
cat mission/protected.txtrefused write: receipt=502e1b03f6da756c7102cb1296cd9e9f27a183047adec6aa665393b706254cec
authority: protected file unchanged; no operation effectThis submits the registered write operation with a research worker’s capability. Kernel authority checks refuse it. The drill also compares the protected file before and after and checks that the attempted operation has no adapter effect record.
A scheduler assigning an operation does not grant permission to perform it. That distinction survives moving work between coordinators.
5. Spend one allowance across the system
megastart drill allowancerefused inspect: receipt=56b11ccca6b94b429d783208479ce2230980d098cbbf3f153410dc8c81df7903
allowance: protected file unchanged; no operation effectThe six completed operations consume the mission’s six-invocation aggregate allowance. This extra inspection is in the worker’s grant, but the family has no remaining capacity. It is refused before the inspection adapter records an effect. Run this drill after completing the default mission.
Each worker is directly delegated from the same mission authority. The single SQLite authority atomically accounts for the shared family, including read-only operations. Reopening the process preserves consumption. A different initial allowance can be chosen with init --allowance; changing a running worker count does not mint more capacity.
How this maps to delegation and accounting
The pinned kernel rejects multi-hop aggregate-family delegation. Swarm coordinators assign work while the mission authority issues one-hop worker grants. Signed root and coordinator snapshots are retained for verification. The sibling-share registry is a separate admission check: each worker carries 1,000 basis points. The durable aggregate ledger enforces actual invocation consumption across the family.
These are invocation units, with no monetary settlement. An operation interrupted after admission can consume capacity without producing a completed artifact. The artifact count is not a general replacement for the accounting ledger. See Budgets & Metering.
6. Recover an interrupted handoff
Start a second mission for the process failure exercise. The original mission remains available for publication.
megastart --state interrupted init
megastart --state interrupted run --crash-after-repairThe host exits with code 75 after the first four effects and their receipts have committed, before the next swarm receives its handoff. The injection drains its child processes before terminating. Continue in the same directory:
megastart --state interrupted recoverready: 1 host, 3 swarm coordinators, 6 workers; private IPC
reconciled inspect: original receipt retained; no dispatch
reconciled reproduce: original receipt retained; no dispatch
shared capacity: 2/6 remaining (4 committed, 0 reserved)
reconciled repair: original receipt retained; no dispatch
reconciled repair: original receipt retained; no dispatch
shared capacity: 2/6 remaining (4 committed, 0 reserved)
allowed review: receipt=6dec153ac95fb16917fdc62750f24b45d55f02f6f5ae549051611b56afbff5d9
allowed test: receipt=35291378cfed1f0e0746b76000bedd302ab8ab33f7c41bf4b5a366f6c0dc0f02
shared capacity: 0/6 remaining (6 committed, 0 reserved)
candidate: cea65906822fac5001d0fba3789c6fd7a3074b9cd151ce71aa6196af7988efe6
Ready for your review. Run megastart review, or open the mission console.Recovery verifies the original receipts and retained effects before skipping those four dispatches. Only the remaining test and review operations run. The acceptance test compares original effect bytes across process replacement and verifies that the shared allowance remains exhausted afterward.
pub(crate) async fn dispatch(&self, task: &Assignment) -> Result<Value> {
let path = self
.directory
.join("outcomes")
.join(format!("{}.json", task.id));
if path.exists() {
let value: Value = read(&path)?;
anyhow::ensure!(
value["assignment"] == json!(task),
"Operation ID belongs to different work"
);
verify_outcome(&self.directory, &value, &self.host.signer.to_hex())?;
crate::journal::emit(
&self.directory,
"operation.reconciled",
&task.worker,
json!({"operation":task.tool,"id":task.id}),
)?;
println!(
"reconciled {}: original receipt retained; no dispatch",
task.tool
);
return Ok(value);
}
anyhow::ensure!(!self.directory.join("effects").join(format!("{}.json", task.id)).exists() && !self.directory.join("requests").join(format!("{}.json", task.id)).exists(), "Operation has no retained outcome; unresolved: inspect kernel receipts and effects before any retry");
let cap = self
.authority
.workers
.get(&task.worker)
.context("Worker has no capability")?;
let call = request(cap, "workspace", &task.tool, task.input.clone());
self.evaluate(task, call).await
}A request retained without a conclusive outcome is unresolved. The host stops instead of treating the absence of a response as permission to repeat an effect. A different crash window needs reconciliation against the kernel receipt and the resource that owns the effect. Shared Worker Fleet develops this pattern further.
7. Authorize the exact candidate
megastart drill approval
megastart statusrefused publish: receipt=008d05655c1b49b4000445fc392dd4861bda62b49ba2cf6e5e491303e0bc86c4
publication: approval required; release/ absentRead the candidate source, test results, and mechanical review. When you decide to publish it locally, replace CANDIDATE_SHA256 below with the proposal’s candidate_sha256:
megastart approve --candidate CANDIDATE_SHA256allowed publish: receipt=56990e50a3930980f85e16aa7c97ed268abb5c4ee5c2490b32f6837307dbffc4
publication: approved candidate published to release/This operator command signs an approval bound to the retained request and exact proposal. The publisher rechecks the candidate’s bytes before atomically creating mission/release. Repeating a completed approval reconciles the original result. A different candidate needs its own tests, review, and decision.
Publication here creates a local release directory. Connecting a deployment service is another operation with its own authority, credentials, and recovery contract.
8. Verify the evidence away from the host
megastart key
megastart export --output evidence
megastart --state evidence verify --trusted-key TRUSTED_KERNEL_KEYFor your own reference run, keep the public key printed by key as your selected trust anchor and substitute it for TRUSTED_KERNEL_KEY. Another party should obtain the expected signer through its own trusted channel. The evidence directory can be copied to another machine with the verifier binary; it contains no original database or private keys.
{
"published": true,
"refused": 3,
"trusted_kernel": "c4d3c4b4393499cb4cbe451335e2f1fb5461813840883bcbf785d33fda199cbf",
"verified_receipts": 10
}Verification checks signatures, operation identity, signed output hashes, and retained effects. It establishes consistency of the supplied records under the selected key. It cannot establish that no activity was omitted, that an unfamiliar signer should be trusted, or that a later external effect occurred.
9. Give the system your next mission
Start with one concrete change. Add this case to project/tests.rs, then initialize a fresh mission. Both candidate workers must now face the extended harness:
#[test]
fn a_single_element_keeps_its_value() {
assert_eq!(moving_average(&[u64::MAX], 1), Ok(vec![u64::MAX]));
}megastart --state next-mission init --project project
megastart --state next-mission runThen replace the bounded repair planner with one suited to your project. Keep source identity, immutable tests, scoped operations, and publication approval. A new source layout needs an explicit adapter; the supplied transformation rejects layouts it does not recognize.
- Connect a model-backed worker through the existing bounded host loop. Model credentials remain on the execution host.
- Adapt research assignments to retained observations and changing evidence.
- Extend the software factory with a broader repair and review process.
- Exercise cancellation and failures at more points in the operating lifecycle.
The reference uses trusted local source and test binaries. Separate processes and candidate directories are workspace organization; OS isolation belongs to the host deployment. Configure a sandboxed executor before accepting untrusted code. Moving workers to other machines also requires authenticated transport and a deliberate authority-store configuration.
Operational limits and recovery
- Only one host may own a mission directory at a time. A competing host fails its exclusive lease.
- Compiler and test subprocesses have 30-second deadlines. Their output stays in retained files and is read with a size bound.
- Capabilities expire after 24 hours. Preserve the old evidence and explicitly initialize a new mission when authority expires.
- Ctrl-C preserves state. Use recover before retrying work; inspect unresolved requests at their effect owner.
- A failed test or review leaves the candidate unpublished. The default mechanical review recognizes the documented bounded transformation; it does not assess arbitrary generated code.
Download integrity and source reference
The archive includes a per-file SHA-256 manifest. Its locked Chio dependencies use the public revision 9ffca8d6.
9dcbecec5bf9681c301ffd0bf7a2eeea685ec8b8b5911ac180692f66cf292050