<deploy_home>/orbi.toml (it sets ORBI_CONFIG); the CLI reads --config PATH, else $ORBI_CONFIG, else ./orbi.toml in the current directory. A read-only command (status, doctor, session, check) given neither flag nor variable, with ./orbi.toml absent, resolves the single installed unit’s config instead. Relative paths are resolved from that file. Run orbi check to validate it before starting a tick.
Repositories and paths
Scheduling
Model provider
The three
review_pi_* rows let the independent review run on a different model than the implementation — see Reviewing with a different model.
Prompts and context
Delivery behaviour
Steering
Steering lets the Runner poll the Issue for a trusted correction and restart the active delivery with that correction.steering_max_rounds bounds those restarts so an active delivery cannot be redirected forever. A polling failure is a pure bypass: it is logged, but never makes the delivery fail. These three keys may be set in a repository’s .github/orbi.toml; a declared repository value wins over the host value, and an omitted key falls back to the host. steering_poll_seconds must be a positive finite number; there is no additional floor.
See the delivery_steered, steering_limit_reached, steering_poll_failed, and steering_limit_notice_failed rows in Operations.
Health
Notifications
Orbi can reach the person who owns the queue outside GitHub: when it NEWLY addsai-blocked, ai-needs-detail or ai-awaiting-merge to a task, it sends ONE Telegram message (private chat or group) naming the state, owner/repo#N <title> and the Issue link. The human-review gate (human_review_gate) also sends ONE message — Waiting for your review — once per delivery: when its PR opens and the checklist asks a person to confirm something (a non-empty column 2), next to that checklist. A delivery whose column 2 is empty needs no human and sends nothing, and later ticks never repeat the message. A label a person adds by hand is their own action and sends nothing. Sending is a pure bypass — a failure is recorded as the notify_failed journal line (Operations) and never fails a delivery or changes a label.
A message that is a problem the person must resolve — ai-blocked, ai-needs-detail and the human-review wait — ends with the community help line Need help? Join the Orbi community: https://t.me/+kJRTTpFGBRU0M2Y9; a normal handoff (ai-awaiting-merge, a merged PR, orbi notify test) does not. Orbi’s GitHub comments follow the same rule: the clarification comment, a human-review checklist whose column 2 is non-empty, and the blocked failure diagnostic end with that line — never a comment that does not ask a person to step in.
The bot token is NOT a config key: it lives only in
<deploy_home>/.orbi/env as ORBI_TELEGRAM_BOT_TOKEN=..., is redacted from the journal, and is not passed in the Pi session’s environment. That environment filter is the whole guarantee: the Pi process runs as the Runner’s user, so a session can still read <deploy_home>/.orbi/env itself. There is no separate notification language: the fixed messages follow the host-level message_language (Issue #1660, default en), never a repository’s .github/orbi.toml override — the message goes to a person, not into the repository.
ORBI_TELEGRAM_BOT_TOKEN=... to <deploy_home>/.orbi/env, send /start to the bot (private) or add the bot to the group and post a message there, open https://api.telegram.org/bot<token>/getUpdates and copy message.chat.id (group ids start with -), set telegram_chat_id, then run orbi notify test. A chat id without a token is reported every tick (notify_failed reason=not_configured), by orbi doctor and by orbi notify test — but never blocks a delivery, because .orbi/env and orbi.toml are separate files that can lag each other.
Each tick reads this config when it starts, so a change applies from the next tick that starts; a delivery already running keeps the settings it started with. Tickets waiting in other ways — one that already carries the human-only ai-human-review label, or a milestone confirmation ticket — send nothing.
A merge is announced too: on every tick with notifications on, Orbi reads the repository’s most recently updated merged pull requests and sends ONE message per PR Orbi opened (the delivery branch orbi/<owner>-<repo>-issue-<n> — an orbi/ prefix alone, such as a self-named orbi/manual, is not Orbi’s) merged since the last check — Orbi · Code merged: owner/repo#N <title> plus the PR link, in the host message_language. The first tick after notifications are enabled (or re-enabled, or after a missing token is fixed) announces nothing for merges that already happened: it creates the watermark <repo_dir>/.orbi/notify-merged-since from the newest merge and only later merges are announced. Turning notifications off deletes that watermark, so a later re-enable never replays the gap; a failed read is one notify_failed reason=merged_check_failed journal line and the next tick retries. Two limits: more than 100 pull requests updated between two ticks can push a merge off the read page, and it is then not announced; and while a single-slot Runner is busy with a delivery, the next tick — and so the message — waits until that delivery ends.