Configuration

All runtime configuration lives in ~/.orch/config.yml (ORCH_HOME), unless overridden via the ORCH_HOME environment variable.

Config Reference

config.example.yml in the orch repo is a short starting config. This table lists every key. Run orch config <key> to read the live value for any dotted key (e.g. orch config engine.tick_interval).

Per-Project Config

Drop a .orch.yml (legacy .orchestrator.yml is still supported) in your project root to override global config (project-level keys take precedence over global).

# ~/projects/my-app/.orch.yml
gh:
  repo: "myorg/my-app"
  project_id: "PVT_..."
workflow:
  enable_review_agent: true
router:
  fallback_executor: "claude"

• Project config is deep-merged with global config (project wins)
• The engine reloads the file when it changes, without a restart (see Hot reload)
• Use orch project board sync to (re-)discover project / status / estimate field IDs and persist them into the project's .orch.yml

Hot reload

The engine watches ~/.orch/config.yml and every project's .orch.yml. A change reloads the values in place, with no restart and no interruption to a running agent. Each changed key is logged with its old and new value, so orch log shows what an edit did.

engine.max_parallel resizes the dispatch pool live. Raising it hands out the extra slots at once. Lowering it never cancels a running task: orch stops handing out slots and takes the permits back as tasks finish, so the limit in force settles at the new value. The dispatch pool resized log line reports in_force and target while a shrink is still settling.

A file that does not parse is ignored: the last good values stay in force and one error is logged per breakage. Fix the file and the next save reloads normally.

A project added to projects: is picked up on the next save — its backend connects, its subscribers start and its issues are ingested on the following sync tick. A failed GitHub health check does not hold the project back: it starts anyway and the next sync tick retries, so a project added while GitHub is rate limited or unreachable still runs.

These settings still need orch service restart. Editing one logs config changed, takes effect after restart with the key, so the reload never looks like it applied. The value is not logged, because channels.* holds bot tokens.

Skills

Install skills on the agent. Claude Code, Codex, and the other agents keep their own skill directories. Name the skill in the task body when the task should use it.

A skills: list or router.default_skills left in a config file has no effect.

Secret values

These keys hold secrets: channels.telegram.bot_token, channels.discord.bot_token, channels.slack.bot_token, webhook.secret, relay.token and gh.app.private_key. Each takes one of three forms, so the config file need not hold the secret:

A reference is the whole value: ${NAME} alone, not inside a longer string. An unset variable or a failed passbox read logs a warning naming the key, and that feature stays off.

channels:
  telegram:
    bot_token: passbox:orch/telegram-bot-token
relay:
  token: ${ORCH_RELAY_TOKEN}

GitHub Authentication

Orch resolves GitHub tokens in this order — the first match wins:

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. gh.auth.token config value
4. gh auth token CLI

The simplest setup is just gh auth login. No extra config needed.

Git

orch's own git calls (fetches, rebases, pushes, ls-remote) all start from one helper, git_ops::git(). It reaches github.com over HTTPS with the same token, whether the remote is SSH or HTTPS, and sets commit.gpgsign=false and tag.gpgsign=false, so orch never asks for your SSH key or signing key. The settings are environment variables of that one process: no remote and no .git/config changes, and your own commits keep your signing.

Agents commit as git.name / git.email (default <agent>[bot]), without signing. Their shell pushes over HTTPS with gh's credentials (pushInsteadOf), and agents may not change remotes or url.* rules, since a worktree shares .git/config with your checkout.

Environment Variables

export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

Explicit token in config

# ~/.orch/config.yml
gh:
  auth:
    token: "ghp_xxxxxxxxxxxxxxxxxxxx"

GitHub App

Creating the App, its permissions, installing it and the relay for events are in GitHub App. This section is the config reference.

The App posts reviews only: the APPROVE or REQUEST_CHANGES review with its inline comments, and the orch/review check run. Every other call, pushes, pull requests, comments, labels and reads, uses the owner's gh token, as agents do. GitHub refuses a review from a pull request's author, so the App must never open the pull requests it reviews.

orch looks up the installation per repository (GET /repos/{repo}/installation), since your account and each organization are separate installations. On a repository the App is not installed on, reviews fall back to the ## Automated Review comment. Without gh.app.id, orch behaves as before.

# ~/.orch/config.yml
gh:
  app:
    id: "123456"
    private_key: "passbox:orch/github-app-key"   # preferred, or
    private_key_env: "ORCH_APP_KEY"               # a variable that holds the PEM, or
    private_key_path: "/path/to/app.pem"          # an absolute path

Agents run as your user and can read any file you can, so keep the key in passbox. orch reads a passbox:<name> value with passbox exec --stdin <name> -- /bin/cat and keeps the first line of the output, so store the PEM on one line with \n for each newline, for example awk '{printf "%s\\n", $0}' app.pem | passbox add orch/github-app-key. orch reads the key once after it starts, in the background, and keeps it in memory for the life of the process. A passbox read waits on Touch ID, so until it succeeds orch posts comment reviews, logs one warning and retries every 5 minutes with at most one prompt pending. Debug builds and tests never load the App.

orch signs an RS256 JWT, exchanges it for an installation token per installation, and refreshes each token 10 minutes before it expires. If the App review cannot be submitted, orch posts the decision as the ## Automated Review comment instead.

Review mode

review.mode picks how a project's pull requests are reviewed. The project's .orch.yml wins, then the global config, then the default comment.

review:
  mode: app   # or comment

In app mode the App review is the decision and no comment is posted. The ## Automated Review comment goes out only when GitHub refuses the App review, and the gate reads it when the App has no review on the head. A review and the check run belong to the head sha the agent reviewed, so a new push makes the PR pending again, except a base update orch makes in approved, which carries the approval (see Review Agent). Issues on lines outside the diff stay in the review body, since GitHub refuses an inline comment there. A project in app mode whose repository does not have the App installed, or a daemon whose App key is not read yet, reviews in comment mode.

Cluster

The cluster section runs orch on several machines. Without it orch runs on one machine. Keys, roles and setup are in Cluster.