IO Harness

Run an AI agent from a typed task contract to a verified result — in your own process, under a permission boundary you control.

You hand it a contract: the task, the file or workspace it may touch, and the criterion that decides whether the work is done. It runs the loop — observe, reason, act, verify, stop — and hands back a result that a check actually passed, with every step in a SQLite trace you can read afterwards.

Quickstart

[dependencies]
io-harness = "0.16"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

use io_harness::{run_with, ApproveAll, OpenRouter, Policy, Store, TaskContract, Verification};

#[tokio::main]
async fn main() -> io_harness::Result<()> {
    let provider = OpenRouter::from_env()?; // OPENROUTER_API_KEY + OPENROUTER_MODEL
    let store = Store::memory()?;

    let contract = TaskContract::new(
        "add a hello function returning 42",
        "src/hello.rs",
        // Not a substring check: this compiles the file the agent produced.
        Verification::CompilesRust,
    );

    // src/ is writable; secrets/ is refused outright and never reaches a human.
    let policy = Policy::default()
        .layer("app")
        .allow_read("*")
        .allow_write("src/*")
        .deny_read("secrets/*");

    let result = run_with(&contract, &provider, &store, &policy, &ApproveAll).await?;
    println!("{:?}", result.outcome);
    Ok(())
}

Requires Rust 1.88 or later. The floor comes from rmcp, which publishes no rust-version of its own, so cargo cannot catch it at resolve time — on 1.87 the build fails inside that dependency rather than here.

What it does

The loop. A [TaskContract] names the goal, the subject, and the verification criterion. Single-file mode edits one file. Workspace mode gives the agent grep, find, read_file and write_file across a repository root.

Verification that executes. A criterion can compile the produced file or run a test against it, in a sandbox, so a substring stub cannot pass. What a passing gate does and does not prove is stated exactly in the verification guide — it is narrower than it reads.

A permission boundary. Layered, deny-first rules decide what the agent may read, write, execute, and connect to. Anything marked ask goes to an approver that can approve, deny, or defer past the end of the process and resume on a human decision later. Every refusal and decision is in the trace, attributed to the rule and the layer that produced it.

Budgets and stop conditions. Steps, wall-clock time, and token spend are capped. A tree of agents draws from one shared ledger no spawned contract can raise.

Agent composition. A root run can spawn contained sub-agents over a shared workspace, nested, many at once. A child inherits its parent's policy and can only narrow it — never grant itself what the parent lacks.

An execution sandbox. Model-produced code runs in an ephemeral sandbox with an isolated workdir, resource caps that kill rather than throttle, and network denied by default. Native backends on macOS and Linux over a portable floor that runs everywhere.

Durable, unattended runs. After every completed step the trace, the budget draw, and a checkpoint commit in one transaction. A crash resumes the whole tree where it stopped: completed steps are not re-run, the budget is not double-charged, and an irreversible action already taken is not taken twice.

Providers, with fallback. OpenRouter, Anthropic, and OpenAI behind one trait, over the crate's own HTTP+SSE client. A provider that is down or rate-limited falls back to the next configured one; failures are classified so a caller can tell a retryable transport error from a terminal one.

Extensibility, in-process and out. Implement the Tool trait for something your program already does, or point the harness at MCP servers over stdio or streamable HTTP. Skills are markdown instruction files that shape how the agent approaches a class of task, with no Rust at all.

Context that stays relevant. Each turn is assembled to fit a stated share of the token budget: superseded observations are compacted, and an observation a later write invalidated is re-read rather than trusted. Durable memory keyed to the workspace survives between runs.

Observation and replay. Register an observer and be called as the run happens — steps, tool calls, approvals, refusals, spend draws, retries, fallbacks, outcomes — instead of polling the store. A recorded provider replays a case so it runs identically twice.

Documents and images, behind opt-in features: spreadsheets, Word, PowerPoint text, PDF, and barcode decoding, each gated on the real path the model named; and image passthrough to any provider whose model accepts one.

Git, as fixed-argv built-ins: status, diff, log, add, and commit, so a run ends as a reviewable commit rather than a working tree someone has to reconstruct. The model supplies paths and a message, never a subcommand or a flag, so push, fetch, reset and rebase are unreachable by construction.

Guides

docs/CAPABILITIES.md indexes them. docs/CONTRACT.md is the public contract: what is stable, what may change, and the limits that hold today.

Feature flags

Everything below is off by default. The default build compiles no optional dependency at all.

Platform support

The full suite runs on all three in CI.

Stability

The crate is pre-1.0 and stays pre-1.0 until its owner says otherwise. A minor release may break the public contract — SemVer permits it below 1.0, and this project uses it. What you can rely on is not that a break will not happen, but that when it does it is marked in CHANGELOG.md with a migration note saying what to write instead, and that a renamed or removed item goes through a deprecation cycle rather than vanishing between two releases.

docs/CONTRACT.md states the whole of it.

Part of initorigin

IO Harness is one of the initorigin products:

io-harness is the only public repository today, which is why it is the only one linked. io-cli and io-studio open when they release.

Contributing

Read CONTRIBUTING.md. Work branches from develop, lands via PR, and every user-facing change updates CHANGELOG.md. Releases follow docs/RELEASE_PROCESS.md.

Security

Report vulnerabilities per SECURITY.md.

License

Apache-2.0. Copyright 2026 Aakash Pawar (InitOrigin). See LICENSE and NOTICE.