Backend Setup

Every live backend needs its native CLI or server installed and authenticated before a flow runs.

Backend	Tag	Constructor	Requirement
Claude	claude	claude()	claude-agent-acp on PATH, or ORCA_CLAUDE_ACP_COMMAND set; ORCA_CLAUDE_TRANSPORT=stream-json falls back to the authenticated claude CLI
Codex	codex	codex()	codex CLI on PATH and authenticated
OpenCode	opencode	opencode()	opencode CLI on PATH; Orca manages opencode serve
Pi	pi	pi()	pi CLI on PATH and authenticated

Use selectBackend() when the flow should honor --backend:

const selected = selectBackend({
  default: "codex",
  config: { readOnly: true },
  perBackend: {
    opencode: { model: "openai/gpt-5.5" }
  }
});

Resolution order:

1. ORCA_BACKEND chooses the backend tag; empty or unset uses default.
2. config applies to every backend.
3. perBackend[tag] overrides shared config for one backend.
4. ORCA_BACKEND_MODEL overrides perBackend[tag].model and config.model.

Run the opt-in live smoke only from a configured machine:

ORCA_REAL_BACKEND_SMOKE=1 ORCA_REAL_BACKEND=codex bun test tests/integration/real-backend-smoke.test.ts

Default CI and bun run verify do not require backend credentials.