The open-source substrate for domain-specific harness checkpoints.
Build, evaluate, and govern the harness around each model × task pair.

English · 简体中文

Documentation · Install · Quickstart · Why Iteron · Architecture · Contributing

[!WARNING]
Pre-alpha; code execution is unconfined by default. Iteron is intended for
development and evaluation, not unattended use on sensitive repositories.
Use --ask-permissions to restore the capability gate and --confine for
macOS Seatbelt or Linux bubblewrap. Windows has no code-execution sandbox;
--confine refuses command execution there.

Iteron is an open-source substrate for building, evaluating, and governing
harness checkpoints for domain-specific AI agents. It provides modular Rust runtime
contracts for context, tools, policies, permissions, evidence, and the checkpoint
lifecycle. A terminal coding agent is the first reference implementation, with
interactive work, bounded automation, provider routing, durable sessions,
verification, and machine-readable output. The workspace and latest public
release are v0.0.20.

Install

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Plantcore-AI/Iteron/releases/latest/download/install.sh | sh

Windows PowerShell:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; Invoke-RestMethod -Uri 'https://github.com/Plantcore-AI/Iteron/releases/latest/download/install.ps1' | Invoke-Expression

The v0.0.20 release publishes macOS arm64, Linux arm64, Linux x86-64, and
Windows x86-64 binaries. The installer verifies the selected archive and
installs for the current user without elevation. Windows distribution does not
change the sandbox boundary described above. See the installation and
verification guide for version pinning,
checksums, attestations, and source builds.

Verify shell resolution without loading a provider credential:

command -v iteron
iteron --version

Quickstart

Validate and store a provider credential outside the repository:

iteron setup --byok glm

Open a repository and start the full-screen interface:

cd /path/to/repository
iteron

Inside the TUI, describe the outcome you want. Use /model to choose an
account-visible model, /permissions to inspect authority, and /help for the
command registry.

For bounded one-shot work:

iteron -p -C /path/to/repository \
  --max-turns 24 \
  --verify 'cargo test --workspace --all-targets --locked' \
  "Fix the failing test, verify the change, and summarize the evidence"

For an untrusted repository, enable both controls:

iteron -p -C /path/to/untrusted-repository --ask-permissions --confine \
  "Explain what this repository's build script does"

Continue with the five-minute quickstart,
Setup and BYOK, and permissions and
sandbox guide.

Why Iteron

Harness checkpoints

Iteron's central design thesis is that agent behavior comes from the interaction
of a frozen model, a task, and the harness around them:

agent behavior = frozen model × task × harness

A harness checkpoint is the typed, versioned bundle of context, prompts,
tools, planning, budgets, verification, and recovery policies selected for a
measured model-task region. Quality, cost, latency, and reliability remain
separate outcomes; permissions, evidence integrity, and hard resource ceilings
remain fixed constraints.

This thesis guides Iteron's architecture without changing the everyday product
surface: users install one CLI, choose a provider, work in the terminal, and get
bounded execution with durable evidence. Read Harness
checkpoints for the search surface,
sensitivity model, applicability rules, and current implementation boundary.

Architecture

Iteron freezes authority in the host and lets typed harness policies propose
bounded work. Offline candidates move through independent evaluation, human
promotion, and a content-pinned registry before a resolver can install them into
runtime slots.

Iteron optimizes harness artifacts only. Base-model weights and adapters are
frozen. Historical SFT, preference, GRPO, and RL names in the wire vocabulary
describe producer provenance for a harness artifact; they do not authorize model
training or trajectory export for model training.

The current codebase is a modular monolith. The fixed-kernel boundary above
is a target contract and extraction direction, not a shipped microkernel claim.
The architecture guide, claim
sheet, and project
status keep current implementation facts separate from
the target.

What ships today

• Interactive TUI and bounded one-shot text, JSON, and stream-JSON interfaces.
• Anthropic Messages, OpenAI Responses, and OpenAI-compatible Chat adapters.
• Built-in profiles for Anthropic, OpenAI, DeepSeek, GLM, MiniMax, and
  Fireworks, plus operator-defined compatible routes.
• Workspace read, search, edit, shell, Git, web, memory, skills, hooks, external
  tool servers, and verification primitives with typed capabilities.
• Permission rules behind --ask-permissions; macOS Seatbelt and Linux
  bubblewrap backends behind --confine.
• Hash-chained local sessions with resume, continue, fork, checkpoint, and
  replay-oriented contracts.

Iteron remains pre-alpha. It does not claim production readiness,
confidentiality isolation, complete microkernel conformance, live
self-evolution, or benchmark superiority. Current evidence and open work are
tracked in the claim sheet, project
status, and roadmap.

Documentation

Contributing

Bug fixes, tests, documentation, provider adapters, evaluation fixtures, and
carefully scoped features are welcome. Read CONTRIBUTING.md,
follow the Code of Conduct, and browse the good first
issues.

Governance and leadership

Jamal Cao @fr0m-scratch · Creator and Project Lead Sets Iteron's direction and holds final human override authority under the public governance contract.

Maintainer count is intentionally not fixed. Humans claim coherent module or
invariant boundaries, accept ongoing responsibility, and use protected review
paths. See GOVERNANCE.md and
OWNERSHIP.md.

Community contributors

@gomnitrix

@XZhouuuu

@yadonkai

Security

Do not report vulnerabilities in public issues. Use GitHub's private Report a
vulnerability flow described in SECURITY.md. Never include
credentials, customer data, private session records, or weaponized exploit
material in public channels.

License

Iteron is licensed under the Apache License, Version 2.0. No CLA is
required.