Quickstart¶
Use a disposable Git repository for the first run. Iteron is pre-alpha; its ordinary coding mode uses workspace-scoped execution and write boundaries, not a guarantee of safety against hostile code or concurrent filesystem manipulation.
1. Build the executable¶
From the Iteron source tree:
The examples below use /path/to/Iteron/target/release/iteron. Replace it with
iteron if you installed the binary on PATH.
2. Set up a provider credential¶
With no provider selected, Iteron first reuses a validated last-success route;
otherwise it prefers locally credentialed openai, then another locally
credentialed provider. A catalog entry is not an account grant.
The supported BYOK wizard validates a key before writing it to a private
operator-owned file:
Iteron never writes credential values into repository configuration. An environment variable supplied by your shell or secret manager remains available as an alternative and takes precedence over the stored file.
See Setup and BYOK for all six built-in providers, credential rotation, and status checks. You can also declare a user-defined provider.
3. Open the TUI¶
When both stdin and stdout are terminals, the interactive TUI is the default. Ask for a bounded, reviewable task, for example:
Use /status to inspect the resolved model, effort, permission mode, cost state,
working directory, and run id. Use /model, /effort, or /mode to inspect or
change session settings.
4. Choose the authority posture deliberately¶
The shipped default uses acceptEdits with dangerous broad host authority.
Use --ask-permissions or an explicit gated --mode for approval checks,
--confine for shell sandboxing, and --mode plan for a read-only run. Review the
permission and sandbox contract before
opening an untrusted repository.
5. Run a one-shot task¶
/path/to/Iteron/target/release/iteron -p -C /path/to/test-repository \
"Find the failing test, explain the cause, and stop without editing"
One-shot mode defaults to broad bypass. It has no approval channel, so an
operation that resolves to "ask" under an explicit gated mode fails closed;
pass --ask-permissions only when that stricter refusal is intended.
For automation, use the stable machine-output modes described in one-shot and automation.