Aegis Orchestrator
Zaru CLI

Zaru CLI Configuration

Where the zaru program reads its settings, every configuration key it reads, and the project file zaru.toml.

Where settings come from

Zaru reads settings from five layers. A later layer overrides an earlier one:

LayerWhereWhat it may set
1. built-inthe program's own defaultseverything
2. user config~/.zaru/config.tomlevery key
3. project config./zaru.toml in the directory you run inonly [project], [runtime] and [[validator]], with the limits below
4. environmentvariables named ZARU_ plus the keyevery key that holds text, a number or true/false
5. flag--runtime, --model, --moderuntime.tier, model.default, tools.mode

zaru config explain <key> prints the key's value at every layer and marks the one in effect.

The environment variable for a key is ZARU_ followed by the key in upper case with its dots turned into underscores: model.default is ZARU_MODEL_DEFAULT, runtime.max_iterations is ZARU_RUNTIME_MAX_ITERATIONS. ZARU_CREDENTIAL_KEY is the one exception: it holds the credential store's encryption key (see Installation) and is not a configuration key.

An unknown key is refused, not ignored. A misspelt key in either file, or a ZARU_ variable that names no key, stops the program with a message naming the key, the layer, and the nearest key that does exist.

Keys and tokens do not belong in the files. A value in config.toml or zaru.toml that is shaped like a bearer token is refused. Store keys with zaru providers keys add and Carbon Forge (formerly Nuclear Notes) tokens with zaru notes tokens add.

Every key

These are all the keys the program reads at commit f9deca3d. A key marked "not from a project" is refused if ./zaru.toml tries to set it, because a repository you cloned must not be able to change where your prompts go or how much Zaru asks you.

Models and providers

KeyHoldsDefaultMeaning
model.defaulttextnoneThe model a task uses. --model sets it for one run. A model alias such as cheap as the value means the model that alias resolves to; anything else is the model's identifier.
model.fast, model.smart, model.cheap, model.localtextnoneThe models the other four model aliases resolve to. zaru models shows each alias and what it resolves to.
provider.<alias>.kindtext, not from a projectnoneWhich provider answers for that model alias: gemini, ollama or openai-compatible. <alias> is default, fast, smart, cheap or local. When it is not set, the first of gemini, ollama, openai-compatible that is usable is chosen: gemini when a Gemini key is stored, the other two when you configured their endpoint.
provider.gemini.endpointtext, not from a projecthttps://generativelanguage.googleapis.comWhere Gemini is reached.
provider.ollama.endpointtext, not from a projecthttp://localhost:11434Where the Ollama server listens.
provider.openai_compatible.endpointtext, not from a projectnoneThe base URL of an OpenAI-compatible server; Zaru adds /chat/completions.
provider.gemini.context_tokens, provider.ollama.context_tokens, provider.openai_compatible.context_tokenswhole numbernoneThe model's context window in tokens. See The context window.
provider.anthropic.endpoint, provider.aegis.endpoint, provider.anthropic.context_tokens, provider.aegis.context_tokensas abovenoneRead, and unused: these two kinds have no client at this commit.
inference.default, inference.fast, inference.smart, inference.cheap, inference.localtextlocal for an Ollama model, frontier for any otherWhether the alias's model counts as local or frontier. It decides the default of runtime.max_iterations at the contained and linked tiers.

Retrying a provider

When a provider's connection fails or breaks, a response stalls, or it answers HTTP 408, 429 or any 5xx, Zaru asks again, a bounded number of times, and says so. Other 4xx answers and refusals the provider states in words are not retried; you are shown the provider's words.

KeyDefaultMeaning
provider.retries3The most retries of one request. At least 1.
provider.retry_backoff_seconds1The first wait; each later wait doubles it (1 s, 2 s, 4 s). At least 1.
provider.retry_jitter_seconds1Up to this many seconds added at random to each wait. At least 0.
provider.retry_wait_ceiling_seconds30The longest single wait, including a longer Retry-After the provider asks for. At least 1.
provider.stall_seconds60A response that has begun and then sends nothing for this long is abandoned as stalled. At least 1. The clock starts at the first byte, so a slow first byte is not a stall.

Permissions

KeyHoldsDefaultMeaning
tools.modetext, not from a projectaskThe permission mode: ask, allow or yolo. --mode and ZARU_TOOLS_MODE set it too. See Permissions.
tools.allowlista list, not from a projectemptyThe calls allow mode runs without asking, each the exact line a prompt shows, such as "cmd.run cargo test". See The allowlist. Set it in ~/.zaru/config.toml.

Runtime

KeyHoldsDefaultMeaning
runtime.tiertext, not from a projectbareThe runtime tier: bare, contained or linked. --runtime sets it for one run. At this commit only bare does anything; the other two change no behaviour, and the program says so.
runtime.max_iterationswhole number; a project may lower it, not raise it1 at bare; at contained, 3 for a local model and 5 for a frontier one; at linked, the sameHow many attempts the validator loop makes. See Validators and the iteration loop.
runtime.max_tool_exchangeswhole number; a project may lower it, not raise it50The most model replies one task may have. At the limit the task stops, the session stays open, and typing continue goes on.

The terminal

KeyHoldsDefaultMeaning
terminal.mousetrue or false, not from a projecttrueWhether a session takes the mouse, so that the scroll wheel scrolls the transcript. false gives mouse selection back to your terminal. With it on, hold Shift while you drag to select text in most terminals.
tipstrue or falsetrueWhether a session shows a standing tip in the hint strip below the input while the input is empty.

Carbon Forge

KeyHoldsDefaultMeaning
notes.<alias>.agent_toolsa list, not from a projectnoneThe tools of the Carbon Forge instance whose token is stored under <alias> that the model may call. With none listed, the model is offered none of them.
persona.pathtext, not from a projectzaru/personaThe Carbon Forge page whose text is sent as the system prompt instead of Zaru's own, read with the token that holds the composer role from the workspace project.workspace names. With no token, no workspace or no such page, Zaru's own system prompt is used.

The project

KeyHoldsMeaning
project.nametextThe project's name.
project.workspacetextThe Carbon Forge workspace this project reads. persona.path is read from it.

The project file, ./zaru.toml

zaru.toml in the directory you run zaru in is the project's own file. It may hold only three tables; any other is refused:

  • [project]: name and workspace.
  • [runtime]: max_iterations and max_tool_exchanges, which it may lower and not raise. tier is refused here.
  • [[validator]]: the commands that check the model's work, below.

zaru init writes an example ./zaru.toml if there is none, and never overwrites one:

[project]
name = "acme-api"
workspace = "acme-engineering"   # the Carbon Forge workspace this project reads

[runtime]
max_iterations = 3

[[validator]]
name = "build"
run  = "cargo build --locked"
expect = "exit-zero"

[[validator]]
name = "test"
run  = "cargo test --all"
expect = "exit-zero"
after = ["build"]

[[validator]]
name = "shape"
run  = "cargo run -- --emit-schema"
expect = { json_schema = "schema/output.json" }

Validator fields

FieldRequiredMeaning
nameyesThe validator's name, which after refers to.
runyesThe command to run.
expectyesWhat counts as a pass: "exit-zero", { exit-code = 2 }, { matches = "<regex>" } or { json_schema = "<file>" }. A schema file must be inside the working directory.
afternoThe names of validators that run before this one. The order comes from after alone; the order of the file only breaks ties. A cycle, a name nothing declares, or two validators with one name are refused before anything runs.

Validators are commands, so none runs until you approve them; see Approving validators.

Files under ~/.zaru/

The program creates ~/.zaru/ readable only by you. What it keeps there:

PathHolds
config.tomlYour settings. You create it; Zaru never writes it.
credentials.jsonStored provider keys and Carbon Forge tokens, encrypted.
sessions/<id>/One directory per session: transcript.jsonl, meta.toml, and the full output of anything the screen shortened.
history.jsonlThe lines you typed at a session's prompt, kept per working directory.
approved-validators.jsonlWhich validator commands you approved, per directory.
admissions.jsonlWhich projects' commands and skills you admitted.
commands/Your own commands and skills. See Commands and skills.
corpus.jsonl, persona.jsonl, tips.jsonlCached Carbon Forge page and atom names, the cached persona page, and which tips were shown.

On this page