---
title: Configuration
description: Full reference for task.yaml configuration.
---


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

## Full example

```yaml
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

sharing:
  attempts: true
  notes: true
  skills: true

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

## `task` section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | string | *required* | Task identifier |
| `description` | string | *required* | What agents should do — included in CORAL.md |
| `tips` | string | `""` | Additional hints shown to agents |

## `grader` section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `entrypoint` | string | `""` | Setuptools-style `module.path:ClassName`. Recommended. Empty falls back to the deprecated `eval/grader.py` discovery. |
| `setup` | list[string] | `[]` | Shell commands run inside `.coral/private/grader_venv/` at `coral start` / `coral validate` time (typically `uv pip install -e ./grader`). |
| `timeout` | int | `300` | Eval timeout in seconds (0 = no limit) |
| `direction` | string | `"maximize"` | `"maximize"` or `"minimize"` — which direction is better |
| `private` | list[string] | `[]` | Files copied to `.coral/private/` (hidden from agents) |
| `args` | dict | `{}` | Extra arguments passed to the grader (accessible as `self.args`) |

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

When `grader.entrypoint` is set, 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.

When `grader.entrypoint` is empty, CORAL falls back to auto-discovering
`eval/grader.py` from the task directory. This still works but emits a
`DeprecationWarning` on load — see
[Writing a Custom Grader](/guides/custom-grader#migrating-from-gradertype--gradermodule)
for the migration guide.

## `agents` section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `count` | int | `1` | Number of agents to spawn |
| `runtime` | string | `"claude_code"` | Agent runtime: `claude_code`, `codex`, `opencode` |
| `model` | string | `"sonnet"` | Model to use (e.g. `opus`, `sonnet`, `haiku`, or full model ID) |
| `max_turns` | int | `200` | Maximum conversation turns per agent |
| `timeout` | int | `3600` | Agent session timeout in seconds |
| `research` | bool | `true` | Enable web search in agent workflow |
| `heartbeat` | list | see below | Periodic actions triggered during eval loop |

### Heartbeat actions

Heartbeat actions run at regular intervals based on eval count:

```yaml
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:

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

## `sharing` section

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

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `attempts` | bool | `true` | Share attempt scores between agents |
| `notes` | bool | `true` | Enable shared notes |
| `skills` | bool | `true` | Enable shared skills |

## `workspace` section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `results_dir` | string | `"./results"` | Where to store run results |
| `repo_path` | string | `"."` | Path to the git repository root |
