Config reference

orch.yaml keys, machine-home files, and ORCH_* environment variables.

orch.yaml config reference

Generated by go run ./cmd/orch-docs by reflecting over config.Config populated with config.Defaults(), with doc comments parsed from source (go/ast). 82 keys across 20 top-level sections.

agents#

yaml key type default meaning
agents.default_cmd string ""
agents.default_preset string "" lookup in Cmds when default_cmd empty
agents.timeout_sec int 600 hard cap per agent run; 0 → default
agents.idle_timeout_sec int 0 IdleTimeoutSec kills a headless agent that produced no stdout/stderr for this long. 0 (default) = off; timeout_sec stays the outer wall-clock bound.
agents.cmds map[string]string {"agy":"agy -p \"{{prompt}}\"","claude":"claude -p --output-format text -n \"{{name}}\" \u003c {{prompt_file}}","codex":"codex exec --approve-for-me \u003c {{prompt_file}}","commandcode":"cmdc --print \"{{prompt}}\" --no-session","copilot":"copilot --yolo -n \"{{name}}\" \u003c {{prompt_file}}","cursor":"cursor-agent -p \"{{prompt}}\" --force --trust","grok":"grok --single \"{{prompt}}\"","kimi":"kimi -p \"{{prompt}}\"","opencode":"opencode run --auto \"{{prompt}}\""} headless BYO templates (ORCH_AGENT_PRESET)
agents.interactive map[string]string {"agy":"agy","claude":"claude","codex":"codex","commandcode":"cmdc","copilot":"copilot","cursor":"cursor-agent","grok":"grok","kimi":"kimi","mimo":"mimo","opencode":"opencode --hostname 127.0.0.1 --port {{notify_port}}","zcode":"zcode"} native TUI launch (orch )
agents.notify map[string]config.AgentNotify {"agy":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"claude":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"codex":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"commandcode":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"copilot":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"cursor":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"grok":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"kimi":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"mimo":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null},"opencode":{"Mode":"http","Method":"","URL":"","Body":"","Headers":null,"Cmd":"","Path":"","Steps":[{"Method":"POST","URL":"{{notify_base}}/tui/append-prompt","Body":"{\"text\":\"[orch #{{msg_id}} {{from_agent}}] {{body}}\\norch msg ack {{msg_id}} --agent {{to_agent}}\"}","Headers":{"Content-Type":"application/json"}},{"Method":"POST","URL":"{{notify_base}}/tui/submit-prompt","Body":"{}","Headers":{"Content-Type":"application/json"}}]},"zcode":{"Mode":"file","Method":"","URL":"","Body":"# orch\n- #{{msg_id}} {{kind}} {{from_agent}}/{{from_session}} → {{to_agent}}/{{to_session}}\n\n{{body}}\n","Headers":null,"Cmd":"","Path":".orch/notices/{{to_session}}.md","Steps":null}} bus delivery templates per preset (http|shell|file)
agents.transport map[string]string null Transport picks how a headless preset is driven: "subprocess" (default — the agents.cmds template, output scraped from the pipe) or "acp" (the agent runs as an Agent Client Protocol server and orch speaks JSON-RPC to it, which is what makes tool calls and permissions visible).
agents.acp map[string]string {"gemini":"gemini --acp","opencode":"opencode acp"} ACP is the invocation that puts a preset into ACP server mode. Defaults cover the CLIs that ship it; a preset with no entry cannot use transport acp.
agents.gateway_route *bool nil (unset) GatewayRoute: when true (default), dispatch injects gateway URL + virt key for token crush.
agents.auth map[string]string null Auth: credential mode per preset, "account" or "gateway" (see ResolveAgentAuth).

ai#

yaml key type default meaning
ai.mode string stub Mode: off | stub | live. Empty → stub.
ai.ollama.host string "" e.g. http://127.0.0.1:11435 (never :11434 — client apps)
ai.ollama.model string "" e.g. llama3.2
ai.providers []config.ProviderEntry null BYO OpenAI-compat endpoints (OmniRoute-style)
ai.passthrough.anthropic.base_url string ""
ai.passthrough.anthropic.api_key string ""
ai.passthrough.anthropic.api_key_env string ""
ai.budget_tokens_day int64 0 BudgetTokensDay caps gateway spend metering (0 = unlimited). UTC day key.
ai.probe_interval_sec int 0 ProbeIntervalSec refreshes /v1/models from upstream (0 = probe once at gateway start).

bus#

yaml key type default meaning
bus.retain_acked string 24h e.g. 24h
bus.retain_unread string 168h e.g. 168h (7d)
bus.max_acked *int 200 hard cap on acked rows; 0 = unlimited
bus.log_max_bytes *int64 524288 bus.log rotate; 0 = unlimited
bus.notices_retain string 24h *.delivered age
bus.surfaced_retain string 48h hook-surfaced/*.ids age

chair#

yaml key type default meaning
chair.guidance.entry_chair *bool true
chair.guidance.multiphase_tasks *bool true
chair.guidance.workers_no_fanout *bool true
chair.guidance.bus_only *bool true
chair.guidance.search_before_create *bool true
chair.guidance.lock_shared *bool true
chair.guidance.disk_memory *bool true
chair.guidance.clarify_before_spawn *bool true

context#

yaml key type default meaning
context.guidance.crush *bool true
context.guidance.externalize *bool true
context.guidance.auto_gateway *bool true
context.guidance.live_zone *bool true only crush/externalize last message (prefix-freeze)
context.guidance.mcp_tools *bool true
context.guidance.protect_tools []string null ProtectTools: tool/function message names that must not be lossy-crushed (Headroom protect-tool-results). Enforced by ctxstore.PrepareTool and gateway prepareMessages against the chat message's tool/function name — a match passes the message through byte-for-byte, uncrushed and un-externalized. Empty → default coding tools list (DefaultProtectTools).
context.threshold_bytes int 4096 default 4096
context.dir string .orch/context default .orch/context (defaultOrchHomePaths)
context.ttl_minutes int 30 CCR blob TTL; default 30
context.hooks.post_tool bool false
context.hooks.pre_compact bool false

daemon#

yaml key type default meaning
daemon.socket string .orch/orch.sock
daemon.addr string 127.0.0.1:0 TCP listen; empty → 127.0.0.1:0
daemon.reap_interval_sec *int nil (unset) ReapIntervalSec is how often the daemon reaps dead sessions and frees their locks, tasks and checkouts. Unset → 60s; an explicit 0 turns the loop off (pointer like gateway_route: "off" and "unset" are not the same).

db#

yaml key type default meaning
db.path string .orch/orch.db

gateway#

yaml key type default meaning
gateway.addr string 127.0.0.1:8788 default 127.0.0.1:8788
gateway.cache.ttl_sec int 0 0 = disabled
gateway.cache.max_entries int 0 0 → 256

guard#

yaml key type default meaning
guard.profile string "" Profile: lite (default recommend) | shared | strict | bring | none
guard.dup.mode string "" Mode: advisory (default, injects context) | block (denies the write) | off.
guard.dup.window int 0 Window is the rolling-hash window in tokens (default 40).
guard.dup.min_tokens int 0 MinTokens is the shortest clone worth reporting (default 60).
guard.dup.max_files int 0 MaxFiles caps repo files compared per call (default 5000).

memory#

yaml key type default meaning
memory.enabled *bool nil (unset) nil → true
memory.brief_on_dispatch *bool nil (unset) nil → true; inject .orch/MEMORY_BRIEF.md
memory.brief_limit int 8 default 8
memory.retention_days map[string]int null type → days; 0/omit = never
memory.okf_dir string .orch/memory/okf default .orch/memory/okf

parsers#

yaml key type default meaning
parsers config.Parsers null ext → lang; empty → DefaultParsers

paths#

yaml key type default meaning
paths.shared string ""
paths.agents string .orch/agents
paths.worktrees string .orch/agents/worktrees
paths.data string .orch

policy#

yaml key type default meaning
policy.mode string "" solo (default) | allowlist
policy.actors []string null allowed actors when mode=allowlist

project#

yaml key type default meaning
project.name string workspace
project.root string .

projects#

yaml key type default meaning
projects []config.ProjectEntry null Projects are registered units inside the workspace (quota counts these).

server#

yaml key type default meaning
server.url string "" e.g. https://api.example.com
server.token_path string .orch/device.token relative path for device/user token; default data/server.token

shared#

yaml key type default meaning
shared map[string][]string {} Shared maps language → absolute or workspace-relative paths (do not mix langs in one path).

telemetry#

yaml key type default meaning
telemetry.work string "" Work: off | on | auto. Empty → auto (push when server linked). Free/unlinked stays local-only.

ui#

yaml key type default meaning
ui.addr string 127.0.0.1:8790 default 127.0.0.1:8790

workspace#

yaml key type default meaning
workspace.name string workspace
workspace.root string .
workspace.primary_languages []string null
workspace.locale string "" Locale is the workshop docs / prose language (orch guard lang). e.g. en, es. Empty = unset → docs lang gate does not enforce. Chat with the LLM may match this; it is NOT the code-language policy.
workspace.code_lang string "" CodeLang is identifiers + user-visible shipping strings (orch guard code-lang). Recommended default at init: en. Comments may stay in Locale / any language. UI translations belong in i18n dictionaries. Empty = code-lang gate off.

Referenced types#

Struct shapes that only appear as a map value or slice element above (no single default — it varies per key/index).

config.ProjectEntry#

field type meaning
id string
path string
kind string

config.AgentNotify#

field type meaning
mode string http|shell|file|none
method string
url string
body string HTTP body or file contents
headers map[string]string
cmd string shell template
path string file path template
steps []config.AgentNotifyStep http chain; if set, ignores single url/body

config.AgentNotifyStep#

field type meaning
method string
url string
body string
headers map[string]string

config.ProviderEntry#

field type meaning
name string
base_url string
api_key string optional; prefer api_key_env
api_key_env string e.g. OPENAI_API_KEY
model string
tier string local|free|cheap|paid
priority int lower = tried first
enabled *bool nil → true

Machine-home files#

Outside any workspace, per user (internal/acctstore.MachineHome: ORCH_HOME, else %LOCALAPPDATA%\Orchemax, else $XDG_CONFIG_HOME/orchemax, else ~/.config/orchemax).

file meaning
ai.yaml user-wide LLM/gateway catalog (config.UserAI); see orch gateway setup
keys.env API key placeholders/ring for gateway providers (config.LookupAPIKey); secrets, never committed
account.json cached non-secret account profile after orch setup login (acctstore.Account)
device.token device token path resolved by orch home / server auth (acctstore.FileDevice)

ORCH_* environment variables#

50 found across client/internal (grep for os.Getenv("ORCH_).

var file:line meaning
ORCH_ACTOR internal/dispatch/dispatch.go:152
ORCH_AGENT internal/cli/cli_bus.go:706
ORCH_AGENT internal/dispatch/ensure_runtime.go:171
ORCH_AGENT internal/mcp/ask.go:37
ORCH_AGENT internal/mcp/verify.go:26
ORCH_AGENT internal/notify/hook.go:34
ORCH_AGENT_CMD internal/config/config.go:800
ORCH_AGENT_CMD internal/config/config.go:822
ORCH_AGENT_PRESET internal/config/config.go:803
ORCH_AGENT_PRESET internal/config/config.go:827
ORCH_AGENT_PRESET internal/dispatch/dispatch.go:112
ORCH_AGENT_TIMEOUT_SEC internal/dispatch/dispatch.go:921
ORCH_AGENT_TRANSPORT internal/config/config.go:531
ORCH_ALLOW_UNLINKED internal/onboard/onboard.go:154
ORCH_CONFIG internal/dispatch/ensure_runtime.go:179
ORCH_CONFIG internal/dispatch/ensure_runtime.go:40
ORCH_FORCE_COLOR internal/onboard/ansi.go:21
ORCH_GATEWAY_BYPASS internal/dispatch/gateway_route.go:91
ORCH_GIT_BASE internal/cli/worktree_cmd.go:61
ORCH_LEASE_SECRET internal/serverclient/events.go:43
ORCH_LEDGER_FORCE internal/dispatch/dispatch.go:436
ORCH_LEDGER_FORCE internal/mcp/spawn.go:51
ORCH_NAME internal/dispatch/ensure_runtime.go:169
ORCH_NOTIFY_URL internal/dispatch/dispatch.go:308
ORCH_NOTIFY_URL internal/notify/notify.go:171
ORCH_NOTIFY_URL internal/notify/notify.go:335
ORCH_NOTIFY_URL internal/notify/notify.go:368
ORCH_NO_SPIN internal/cli/spin.go:59
ORCH_OLLAMA_HOST internal/gateway/providers.go:118
ORCH_OLLAMA_MODEL internal/gateway/providers.go:125
ORCH_REQUIRE_LEASE internal/serverclient/entitlements.go:143
ORCH_ROLE internal/dispatch/dispatch.go:433
ORCH_ROLE internal/dispatch/ensure_runtime.go:175
ORCH_ROLE internal/dispatch/ensure_runtime.go:31
ORCH_ROLE internal/mcp/server.go:130
ORCH_ROLE internal/mcp/spawn.go:17
ORCH_SESSION internal/cli/cli_bus.go:702
ORCH_SESSION internal/dispatch/ensure_runtime.go:163
ORCH_SESSION internal/harness/ide.go:108
ORCH_SESSION internal/mcp/ask.go:156
ORCH_SESSION internal/mcp/ask.go:36
ORCH_SESSION internal/mcp/server.go:161
ORCH_SESSION internal/mcp/verify.go:77
ORCH_SESSION internal/mcp/verify.go:24
ORCH_SESSION internal/notify/hook.go:31
ORCH_SESSION_NAME internal/dispatch/ensure_runtime.go:167
ORCH_SETUP_YES internal/onboard/onboard.go:158
ORCH_SKIP_GATEWAY_AUTOSTART internal/dispatch/ensure_gateway.go:20
ORCH_TASK internal/mcp/verify.go:25
ORCH_TASK_TOKEN_BUDGET internal/circuit/breaker.go:24