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; new ordinary sessions default to dangerous broad host authority.** > Iteron is unsuitable for unattended use on sensitive or untrusted repositories: > the built-in file-write boundary has an unresolved symlink race. Use > `--ask-permissions`, an explicit gated `--mode`, or `--confine` to tighten the > posture; `--mode plan` is read-only. Source now includes Windows LPAC isolation > with retained Job, pipe, and ConPTY owners. Its native runtime and isolation > acceptance is pending; a Windows archive does not establish that acceptance. 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 separate: this workspace targets **v0.0.30**. The [GitHub Releases page](https://github.com/Plantcore-AI/Iteron/releases/latest) identifies the latest published version and its downloadable assets. ## Install macOS and Linux: ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Plantcore-AI/Iteron/releases/latest/download/install.sh | sh ``` Windows PowerShell: ```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 ``` Release packages cover macOS arm64, Linux arm64, Linux x86-64, and Windows x86-64. 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](docs/getting-started/installation.md) for version pinning, checksums, attestations, and source builds. Verify shell resolution without loading a provider credential: ```sh command -v iteron iteron --version ``` ## Quickstart Validate and store a provider credential outside the repository: ```sh iteron setup --byok glm ``` Open a repository and start the full-screen interface: ```sh 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: ```sh 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, use read-only mode or inspect it manually: ```sh iteron -p -C /path/to/untrusted-repository --mode plan \ "Explain what this repository's build script does" ``` Continue with the [five-minute quickstart](docs/getting-started/quickstart.md), [Setup and BYOK](docs/getting-started/setup-and-byok.md), and [permissions and sandbox guide](docs/using/permissions-and-sandbox.md). ## Why Iteron | Principle | Contract | | --- | --- | | **Domain-specific substrate** | Shared runtime contracts let each domain define its model and task profiles, harness policies, evidence, and checkpoints. | | **Terminal native** | Full-screen TUI plus text, JSON, and stream-JSON automation. | | **Bounded runtime** | Explicit ceilings for turns, time, cost, retries, queues, output, and concurrency. | | **Authority separation** | Strategies may propose work; they cannot grant capabilities, relax hard budgets, or rewrite evidence. | | **Durable evidence** | Hash-chained sessions, checkpoints, correlated tool events, and provider-grounded usage states. | | **Provider truth** | Credential-visible discovery and explicit available, disabled, or unknown capability states. | | **Model-task fit** | Harness choices are evaluated for a model and task profile instead of being treated as universal defaults. | | **Modular ownership** | Machine-validated Rust boundaries with accountable human maintainers and protected review. | ### 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: ```text 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](docs/concepts/harness-checkpoints.md) 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.
|
Jamal Cao@fr0m-scratch · Creator and Project LeadSets Iteron's direction and holds final human override authority under the public governance contract. |
![]() @gomnitrix |
![]() @XZhouuuu |
![]() @yadonkai |