Configuration

Every CORAL task is defined by a task.yaml file. This page documents all available options.

Full example

task:
  name: "my-task"
  description: "Optimize solution.py to maximize accuracy."
  tips: "numpy and scipy are available. Timeout is 300s."

grader:
  entrypoint: "my_task_grader.grader:Grader"
  setup:
    - "uv pip install -e ./grader"
  timeout: 300
  direction: maximize
  private:
    - "answers/test_data.csv"
  args:
    program_file: "solution.py"

agents:
  count: 2
  runtime: claude_code
  model: claude-sonnet-4-6
  max_turns: 200
  timeout: 3600
  research: true
  heartbeat:
    - name: reflect
      every: 1
    - name: consolidate
      every: 10
      global: true

islands:
  count: 1
  migration:
    enabled: true
    every: 50
    rank_window: 20
    min_evals: 3
    dest_weighting: score
    max_per_cycle: 2
    notify_island: true

sharing:
  attempts: true
  notes: true
  skills: true

workspace:
  results_dir: "./results"
  repo_path: "."

task section

grader section

The legacy grader.type and grader.module fields have been removed. Tasks that still set them fail to load with a migration error pointing at grader.entrypoint.

Loading your grader

CORAL bootstraps a venv at .coral/private/grader_venv/, runs every command in grader.setup inside it, and spawns a worker subprocess from that venv whenever an attempt needs grading.

grader.entrypoint is required — leaving it empty is an error at load time. See Writing a Custom Grader for the packaged-grader layout.

agents section

Heartbeat actions

Heartbeat actions run at regular intervals based on eval count:

heartbeat:
  - name: reflect        # Built-in: agent reviews progress
    every: 1             # After every eval
  - name: consolidate    # Built-in: agents share knowledge
    every: 10
    global: true         # Uses global eval count (all agents combined)

You can also define custom heartbeat actions with a prompt:

coral heartbeat set review --every 5 --prompt "Review your approach and consider alternatives."

islands section

Multi-island mode partitions a run into isolated agent groups. Agents on the same island share attempts, notes, skills, heartbeat state, roles, and logs. Agents on different islands evolve independently until migration moves an agent between islands.

agents:
  count: 4

islands:
  count: 2
  migration:
    enabled: true
    every: 50
    rank_window: 20
    min_evals: 3
    dest_weighting: score
    max_per_cycle: 2
    notify_island: true

You can also enable it from the command line:

coral start -c task.yaml agents.count=4 islands.count=2

islands.count defaults to 1, which preserves the normal single-island layout. When islands.count > 1, the total number of agents must be at least the number of islands. With agents.assignments, the total agent count is the sum of all assignment counts.

CORAL distributes agents round-robin across islands and rewrites IDs with a birth-island prefix, for example 0-agent-1, 0-agent-2, 1-agent-1, 1-agent-2. The prefix records where the agent started; after migration, the agent may live on a different island.

From inside an agent worktree, CLI commands such as coral status, coral log, coral notes, coral skills, coral wait, coral checkout, and coral heartbeat are scoped to that agent's current island. From outside an agent worktree, read commands aggregate across islands.

Migration options

Migration is ignored when islands.count == 1.

When an agent migrates, its role, per-agent heartbeat config, attempts, and eval logs move with it. Notes and skills stay on the source island as island-local knowledge.

sharing section

Controls what shared state is enabled in .coral/public/:

workspace section