Millrace OS

Long-running agent work needs an operating layer.

Millrace OS is an open-source personal AI operating layer for supervising long-running agentic work. It gives an operator a local control plane for what is queued, what is running, what changed, what is blocked, what needs approval, and what evidence proves a run actually completed.

It is not another chat UI. It is the runtime-facing layer around agent work: durable state, typed contracts, package and capability boundaries, visible failure states, and a Mission Control surface that reads from runtime truth instead of from conversational memory.

What Works Today

The current millrace-os crate is an early, source-runnable foundation. It includes:

• a Rust CLI for local setup, status, diagnostics, foreground daemon ownership, work enqueue, one-step execution-loop proof, evidence export, and runtime read-model projection;
• a SQLite-backed runtime authority for work items, runs, events, artifact refs, approvals, incidents, terminal outcomes, compiled-plan bindings, and Millracer operation records;
• typed contracts for runtime, Mission Control, packages, gateway dispatch, loop packs, evidence packets, and public handoff DTOs;
• a Local Capability Gateway boundary for package-backed adapters, capability checks, local MCP-compatible tool exposure, redacted receipts, and package diagnostics;
• strict optional-package metadata validation, registry and compatibility fixtures, checksum checks, immutable skill references, and caller-owned package lifecycle state;
• a dependency-free Mission Control shell that renders app-facing runtime projections and command availability metadata without mutating runtime state;
• deterministic public evidence export so claims can be regenerated and checked.

The project is under active development. It does not yet ship a signed desktop app, hosted service, broad package catalog, or durable OS service manager.

Install

Install the published CLI:

cargo install millrace-os

Confirm the binary is available:

millrace-os --help

Create a scratch runtime store and inspect first-run readiness:

STORE=/tmp/millrace-os-demo.sqlite
millrace-os --store "$STORE" --json setup-status --workspace-root .
millrace-os --store "$STORE" --json status
millrace-os --store "$STORE" --json doctor

Run the bounded foreground daemon in another terminal when you want daemon-owner evidence:

millrace-os --store "$STORE" daemon --foreground

Type shutdown in that foreground daemon terminal to stop it cleanly.

From Source

git clone https://github.com/tim-osterhus/millrace-os.git
cd millrace-os
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
npm run verify --prefix apps/mission-control-shell
scripts/public-safety-scan.sh
scripts/package-budget-check.sh
scripts/performance-baseline.sh --skip-public-demo

Refresh the deterministic public demo evidence:

scripts/refresh-public-demo.sh

The refresh script writes generated stores, packets, and Mission Control projections only to a scratch directory.

How It Fits

Millrace OS sits above the base Millrace runtime and beside agent harnesses such as Codex, Claude Code, or other local runners:

• the harness edits files and emits stage results;
• Millrace owns queue state, runtime state, stage contracts, recovery paths, and closure behavior;
• Millrace OS exposes the operator control plane, package/gateway boundary, command availability, evidence export, and Mission Control read models;
• Millracer is treated as an adapter boundary for scoped runner operations, not as the durable source of runtime truth.

Use Millrace OS when work spans sessions, needs auditable handoffs, must survive partial failure, or needs visible acceptance evidence. Use a direct agent session when the task is small enough that a runtime would add more overhead than value.

Read Next

• docs/getting-started.md - first local run from the published crate or source
• docs/architecture.md - system boundaries and module responsibilities
• docs/runtime.md - runtime state, daemon ownership, CLI behavior, and repair limits
• docs/mission-control.md - the read-only Mission Control shell and command availability model
• docs/packages.md - Local Capability Gateway, optional package metadata, and lifecycle boundaries
• docs/evidence.md - public-safe evidence packets, demo refresh, and handoff DTOs
• docs/release.md - validation commands, performance surfaces, package budget, and publish checklist
• docs/troubleshooting.md - common local failure modes and recovery steps

License

Millrace OS is released under the Apache License 2.0. See LICENSE.