Configure agents, presets, transport

Detect installed agent CLIs, pick launch presets, and choose how each one authenticates and talks to orch.

Goal#

Tell orch which coding-agent CLIs are on your machine, how to launch each one (headless dispatch vs. native TUI), which credentials it should use, and — for the few that support it — how to drive it over the Agent Client Protocol (ACP) instead of scraping a subprocess pipe.

Steps#

1. Scan your PATH for known agent CLIs (Claude, OpenCode, Cursor, Codex, Copilot, …):

   orch agents scan
   

   Writes a snapshot; does not touch orch.yaml yet.

2. Review what was found:

   orch agents show
   

3. Apply new detections to orch.yaml (never overwrites presets you already edited):

   orch agents apply
   

4. Presets live in two maps in orch.yaml:

   • agents.cmds.<preset> — headless BYO template used by dispatched workers, e.g. claude -p "{{prompt}}". Built-ins ship for copilot, claude, opencode, grok, kimi, commandcode, agy, codex and cursor.
   • agents.interactive.<preset> — native TUI launch used by orch <preset> (no prompt required), e.g. codex, cursor-agent, claude, opencode --hostname 127.0.0.1 --port {{notify_port}}.

   Edit either map directly in orch.yaml to add a CLI orch doesn't know about, or to change an existing template. Dispatching a recognized CLI preset that has no agents.cmds.<preset> entry fails loudly to the Chair (preset "<preset>" has no headless command: set agents.cmds.<preset>) instead of silently running the stub agent — add the entry to fix it.

5. Choose the credential mode per preset with agents.auth.<preset>:

   • account — the agent keeps its own plan login; orch injects only its own ORCH_GATEWAY_* vars, never provider keys.
   • gateway — the agent authenticates with orch's virtual key and all model traffic routes through the local gateway.

   Defaults: codex and cursor are account (forcing credentials on them drops the subscription's connectors). claude is gateway only when an Anthropic passthrough key is configured, otherwise account. Everything else defaults to gateway.

6. For CLIs that expose an Agent Client Protocol server mode — currently gemini (gemini --acp) and opencode (opencode acp) — set:

   agents:
     transport:
       gemini: acp
   

   ACP makes tool calls and permission prompts visible to orch instead of scraping stdout. Any other preset stays on the default subprocess transport; agents.acp.<preset> holds the invocation orch runs to put the CLI into ACP mode (built-in for gemini/opencode, empty for everything else — a preset with no ACP entry cannot use transport: acp).

7. Set run limits:

   agents:
     timeout_sec: 600        # hard wall-clock cap per run (0 = default)
     idle_timeout_sec: 0     # kill if no stdout/stderr for this long; 0 = off
   

Verify#

orch <preset>

launches the native TUI for that preset. For a headless dispatch, check .orch-agent.log in the session's worktree for the resolved command and any permission/timeout exit codes (124 = agents.timeout_sec/idle timeout, 126 = a headless permission prompt orch couldn't answer).

Undo#

Remove the preset's entry from agents.cmds / agents.interactive, or reset agents.auth.<preset> / agents.transport.<preset> to unset to fall back to the defaults above.

Related#

• gateway-keys-and-connect.md — what agents.auth: gateway actually routes through.
• troubleshooting.md — worker permission timeouts.