/setting-up-coral

name: setting-up-coral
description: One-time machine setup after installing the `coral` CLI — register local agent runtimes as named bindings with `coral setup` / `coral setup agent`, validate them with `coral agents doctor` (incl. a live hello-ping that catches expired auth and model typos), and reference them from a task via `agents.binding`. Use when the user is configuring which agent runtimes/models coral can use, hits a "runtime not found" / auth error when starting a run, or asks how to set up claude/codex/cursor for coral.

Setting up coral (agent bindings)

After installing the `coral` CLI, the one-time machine setup is **registering which agent runtimes you have** as named *bindings*. A binding bundles a runtime + CLI command + default model + runtime options under a short name, stored at:

~/.config/coral/agents.yaml        # honors $XDG_CONFIG_HOME; override with $CORAL_AGENTS_CONFIG

Tasks then reference a binding by name (`agents.binding: claude-opus`) instead of repeating runtime/model in every `task.yaml`. This keeps `task.yaml` portable (topology: how many agents, which roles) and machine-specific details (which CLIs are installed here) in a user-level file that's never committed.

> Bindings store **no credentials.** Authentication stays with each runtime's native login (`claude`, `codex`, `cursor-agent login`, `kiro-cli` setup). `coral setup` only records runtime/command/model metadata. If a run fails to auth, fix it via the runtime's own login, not coral.

1. Detect + create bindings (the fast path)

coral setup

Scans `PATH` for every supported runtime (`claude`, `codex`, `cursor-agent`, `opencode`, `kiro-cli`, `pi`), prints a detection report (✓ = found), then offers a numbered wizard. For each pick it asks for a **binding name**, **model**, and an optional **role-seed file**. After each one it asks "Add another binding for X?" — say yes to make several bindings for the same runtime (e.g. `claude-opus` and `claude-sonnet`). The **first** binding created becomes the default.

• `coral setup --non-interactive` — just print the detection report (CI / piping); creates nothing.

2. Create / update a single binding (scriptable)

For a custom command path, model, or runtime option — or for CI where you can't use the wizard:

coral setup agent --name claude-opus --runtime claude_code --model opus
coral setup agent --name codex-high  --runtime codex --option model_reasoning_effort=high
coral setup agent --name claude-opus --runtime claude_code --model opus --default   # make it the default

`--runtime` accepts a builtin (`claude_code | codex | cursor_agent | opencode | kiro`) or a custom `module.path:ClassName`. Re-running with an existing `--name` updates that binding. Each `coral setup agent` finishes with a lightweight `doctor` pass on that binding.

3. Validate before running

coral agents list                 # numbered; default marked
coral agents show claude-opus     # one binding's resolved fields
coral agents doctor               # validate ALL bindings
coral agents doctor claude-opus   # validate one

`doctor` runs five checks per binding: the binding resolves to a valid spec, the CLI is on `PATH` (or at the configured `command`), `--version` works, the role file exists (if set), and — **by default** — a **live hello-ping** that spawns the runtime with a one-word prompt and waits for a reply. The live ping is what catches the failures the cheap checks miss: **expired auth, broken provider credentials, network issues, model-name typos.**

• `--no-live` — skip the hello-ping (CI / quick sanity check; costs one LLM round-trip per binding otherwise).
• `--timeout SECS` — per-ping wait (default 30s).

When the ping fails, `doctor` points you at the runtime's login flow rather than asking for credentials.

coral agents remove                       # interactive numbered wizard
coral agents remove claude-opus codex-high   # delete one or more by name

Reading a doctor failure

`doctor` tells you *which* of the five checks failed — match it to the fix:

| Failed check | What it means | Fix | |---|---|---| | binding resolves | `agents.yaml` entry is malformed or names an unknown runtime | `coral agents show <name>`; recreate with `coral setup agent --name ... --runtime ...`. | | CLI on PATH | the runtime binary isn't found | install the runtime, or point the binding at it with `--command /abs/path`. | | `--version` works | binary found but won't run | reinstall the runtime; check it runs standalone. | | role file exists | a configured role-seed file was moved/deleted | fix the path or drop the role file from the binding. | | **live hello-ping** | binary runs but the model call fails | **almost always auth or a model typo** — log in via the runtime (table below) and check the model name. Re-run; add `--no-live` only to skip the check, not to fix it. |

Per-runtime authentication

Bindings store **no credentials** — each runtime owns its own login. The hello-ping failing means you log in *here*, not in coral:

| Runtime | `--runtime` | Log in with | |---|---|---| | Claude Code | `claude_code` | `claude` (interactive login) | | Codex | `codex` | `codex` login flow | | Cursor Agent | `cursor_agent` | `cursor-agent login` | | Kiro | `kiro` | `kiro-cli` setup | | OpenCode | `opencode` | `opencode` auth |

Codex reasoning effort is a runtime option, not a model: `coral setup agent --name codex-high --runtime codex --option model_reasoning_effort=high`. For custom or self-hosted models across runtimes, route through the LiteLLM gateway (`agents.gateway` in `task.yaml`): https://coral.compounding-intelligence.ai/docs/guides/gateway

4. Use a binding in a task

Single runtime:

agents:
  binding: claude-opus
  count: 4

Mixed team — one binding per assignment:

agents:
  assignments:
    - binding: researcher
      count: 1
    - binding: implementer
      count: 3

**Preceden