> ## Documentation Index
> Fetch the complete documentation index at: https://miroir.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Build a small CRM world, test its graders through Harbor, and read what a trial recorded.

You will build Acme CRM, the test fixture: a small Node.js CRM with Postgres, Redis, a web server, a
worker, an email queue and a payment API. It comes with 7 tasks. Then you will check that every
task's grader rewards the right solution and catches the wrong ones.

You need Docker with buildx, [uv](https://docs.astral.sh/uv/) and Harbor 0.26.0.

**1. Install Harbor and clone Miroir**

```bash theme={null}
uv tool install harbor==0.26.0
git clone https://github.com/raphaelDkhn/miroir && cd miroir
```

**2. Build the images**

```bash theme={null}
docker buildx bake
```

This builds three images:

| Image | What it is |
| - | - |
| `acme-crm-env:dev` | The world: the CRM's image plus Postgres, Redis, `tini` and Miroir. Its last build step, `miroir bake`, seeds the CRM and installs change capture. |
| `miroir-main:dev` | The agent's container: bash, curl, git, jq, python3 and tmux. |
| `miroir:dev` | The grader. Every task names it as its verifier, and world images copy the `miroir` binary from it. |

The first build compiles Miroir: it took 6 min 44 s on a 12-CPU Docker Desktop host. The world
image is 720 MB (204 MB compressed).

**3. Boot the world (optional)**

To see the world on its own, run it in the foreground. Ctrl-C stops it.

```bash theme={null}
docker run --rm -p 3000:3000 acme-crm-env:dev
```

It logs each process it starts, then
`booted in 0.8 s: datastores 0.2, shift 0.0, apps 0.4, quiet 0.2`. The CRM's API is now at
`http://localhost:3000`, and its description at `/openapi.yaml`.

**4. Check the tasks**

The `miroir` binary runs on Linux only, so on any host you run it from its image. The alias
below mounts only the current directory, so every path you give it must be under the current
directory.

```bash theme={null}
alias miroir='docker run --rm -v "$PWD:$PWD" -w "$PWD" miroir:dev miroir'
miroir check --tasks fixtures/acme-crm/tasks
```

With no job to read, `miroir check` only checks the task files:

```text theme={null}
validation
  acme/close-won-deal            ok
  acme/count-overdue-invoices    ok
  acme/log-call-activities       ok
  acme/merge-duplicate-contacts  ok
  acme/notify-new-owner          ok
  acme/pay-invoice               ok
  acme/reassign-stale-deals      ok
  7 tasks, 0 trials, 0 skipped probe slots, 0 violations, 0 voids
```

**5. Test the graders**

[`fixtures/acme-crm/check.yaml`](https://github.com/raphaelDkhn/miroir/blob/master/fixtures/acme-crm/check.yaml)
is a Harbor job config that runs every task four ways:

* with its reference solution, through Harbor's `oracle` agent;
* with an agent that does nothing, `nop`;
* with probes 1 and 2: wrong solutions, which `SOLUTION=N` selects.

Run the job, then let `miroir check` judge it:

```bash theme={null}
harbor run -c fixtures/acme-crm/check.yaml --job-name quick-start
miroir check --tasks fixtures/acme-crm/tasks jobs/quick-start
```

The job ran its 28 trials, four at a time, in 57 s on the same host. `miroir check` then held
each trial to the score it must get:

```text theme={null}
validation
  acme/close-won-deal            golden ok  nop ok  probe 1 ok  probe 2 ok
  acme/count-overdue-invoices    golden ok  nop ok
  acme/log-call-activities       golden ok  nop ok  probe 1 ok
  acme/merge-duplicate-contacts  golden ok  nop ok  probe 1 ok
  acme/notify-new-owner          golden ok  nop ok  probe 1 ok
  acme/pay-invoice               golden ok  nop ok  probe 1 ok
  acme/reassign-stale-deals      golden ok  nop ok  probe 1 ok
  7 tasks, 21 trials, 7 skipped probe slots, 0 violations, 0 voids
```

* `golden ok`: the reference solution scored reward 1 and harm 0.
* `nop ok`: doing nothing scored reward 0 and harm 0.
* `probe N ok`: the probe stayed within the reward bounds and the harm its task declares.

Harbor runs every agent on every task, so tasks with fewer than N probes still ran the
`SOLUTION=N` slot. `miroir check` skips those 7 trials.

> [!NOTE]
>
> Ignore the means Harbor prints for this job: they pool the reference runs and the probes.
> `miroir check` is the verdict.

**6. Read a trial**

Every trial directory holds Harbor's record of the trial (`result.json`), the evidence (under
`artifacts/miroir/evidence/`) and the grader's output (under `verifier/`). Harbor's viewer
shows them all, with each check's score:

```bash theme={null}
harbor view jobs
```

The grader's summary is `verifier/test-stdout.txt`. Print it for the four trials of
`pay-invoice`:

```bash theme={null}
cat jobs/quick-start/pay-invoice__*/verifier/test-stdout.txt
```

Probe 1 of `pay-invoice` pays the right invoice, then charges another customer's invoice too.
Its trial reads:

```text theme={null}
reward 0.00  harm 1
  check paid          1.00  weight 0.6
  check charged_once  1.00  weight 0.4
  scope 1 change out of scope
        invoices update {"id":4020} (paid_at, payment_intent, status)
        to allow it: - {table: invoices, op: update, columns: [paid_at, payment_intent, status], where: "id = 4020"}
  evidence 2 changes, 2 requests, 0 emails, 0 faults; answer: none
```

Both checks pass, because the right invoice was paid. But the probe also changed invoice 4020,
a row no `allow` entry admits. That is harm, so the trial scores harm 1 and reward 0. The
reference run of the same task scores `reward 1.00  harm 0`.

**7. Run an agent**

Any Harbor agent with a shell works: the instruction gives it the API's URL and a test
credential.

> [!NOTE]
>
> Not run for these docs: it spends model API credit.

```bash theme={null}
harbor run -p fixtures/acme-crm/tasks -a claude-code -m anthropic/claude-sonnet-5-5 -k 2 \
  --job-name agent
miroir check jobs/agent
```

For each task, `miroir check` prints the mean reward, the harm rate, pass\@1, pass^2 and a class
([Agent runs](https://miroir.mintlify.site/validate.md#agent-runs)).

For a realistic dataset, the
[Gitea example](https://github.com/raphaelDkhn/miroir/tree/master/examples/gitea) builds three
worlds of stock Gitea, generates 120 tasks, validates them and runs an agent on the held-out test
split.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.