
miroir
Make, check, serve and train on Miroir envs: reinforcement-learning environments made from a product's Docker image
- GitHub stars
- 40
Install
/plugin install miroir@miroirRun it inside Claude Code after adding the marketplace with /plugin marketplace add raphaelDkhn/miroir.
Contents
Discovered from sourceSkills 1
Miroir
Miroir turns a product's container image into Harbor environments graded from what the agent
actually did to the product. Harbor runs everything else: tasks, agents, sandboxes, jobs,
regrades, publishing. Miroir never wraps harbor run.
Mental model
- A world image is the product plus Postgres,
tini, themiroirbinary and/miroir/miroir.yaml, seeded atdocker buildbyRUN miroir bake;miroir runboots it. - A task is a plain Harbor task directory. The world is a compose service next to
main, where the agent calls the product's own API with a test credential frominstruction.md. - When the agent stops, Harbor's collect hook runs
miroir collectin the world, which writes the evidence: net row changes, sent emails and requests, faults. - Harbor's separate verifier runs
miroir gradewith the task's spec (MIROIR_SPEC): checks scorereward; a change noallowentry admits, a failed gate or a fault isharm, which zeroes the reward. - A grader is valid when the reference solution scores reward 1 and harm 0, doing nothing scores 0 and 0, and every probe (a wrong solution) stays within its declared bounds and harm.
Run miroir on the host
miroir check and miroir draft run on the host, from the Miroir image. The alias sees only the
current directory, so keep every path under it (Harbor's jobs/ is):
alias miroir='docker run --rm -v "$PWD:$PWD" -w "$PWD" miroir:dev miroir'
miroir:dev is what docker buildx bake builds in the Miroir repository; releases publish
ghcr.io/raphaeldkhn/miroir:<major>.<minor>. bake, run and collect run inside the world
image, and grade inside the grader's; none of them runs on the host.
Choose the job
| The user wants to | Then read |
|---|---|
| turn a product into a world | references/environment.md, then references/manifest.md |
| fix a bake, a boot or a collect | references/lifecycle.md, "Failure messages" |
| write or fix a task or its probes | references/tasks.md |
| write or fix a spec | references/spec.md and references/evidence.md |
| generate many tasks | references/tasks.md, "Generate tasks" |
validate graders, read miroir check output | Validate graders |
| publish a dataset | Publish, then Harbor's publish skill |
| train, or pick tasks to train on | Train |
| turn a production snapshot or a ticket into a world or a task | references/environment.md, "From production" |
The references are pages of the docs at https://miroir.mintlify.site. A link in them such as
/validate#trial-checks is a path on that site; /environment, /manifest, /lifecycle,
/tasks, /spec and /evidence are the references themselves.
Look before you write. Find miroir.yaml, Dockerfile.miroir, task directories whose
task.toml holds MIROIR_SPEC, and check.yaml; then the product's own Dockerfile or compose
file, migrations, seed scripts, API description and authentication. The Miroir repository's
fixtures/acme-crm (a CRM,
7 tasks) and examples/gitea
(stock Gitea, three worlds, a task generator) are working examples to copy.
Wrap a product
- Map every process and datastore (command, port, user, environment), what the product sends out, and what runs in the background.
- Write
Dockerfile.miroirfrom the fixture's, andmiroir.yaml: datastores first, a ready probe per server,envpointing mail and outbound URLs at the sinks,bakeandseedcommands,database,sinks,quiet. - Build:
docker build -f Dockerfile.miroir -t my-env:dev .. The bake runs inside the build; a failure names the step, the command or field, and the fix. - Boot:
docker run --rm -p 3000:3000 my-env:devuntil it logsbooted in …. A boot failure names the step and the fix, such as a port that listens off loopback.
The authoring loop
-
Copy a fixture task directory. Set the world image and service in
environment/docker-compose.yaml, and the service inartifactsand[[verifier.collect]]. -
Write
instruction.md(who the agent acts as, the API's URL and credential, the request) andsolution/solve.sh(every callcurl -fsS). -
Give it a placeholder spec,
checks: [{name: todo, sql: SELECT 0}]withallow: [], and runmiroir check --tasks tasksfor the static checks. -
Run the reference twice, then draft the spec from both runs:
harbor run -p tasks/<task> -a oracle -k 2 -n 1 --job-name ref miroir draft jobs/ref/<task>__* -
Paste the draft into
MIROIR_SPECand review it: drop checks the instruction does not ask for, loosen exact text the agent may word its own way, move invariants to gates. -
Regrade instead of rerunning. Bump the minor version, then:
harbor job regrade jobs/ref -p tasks/<task> --job-name ref-2 cat jobs/ref-2/*/verifier/test-stdout.txtThe reference must read
reward 1.00 harm 0. Each out-of-scope change is printed with a paste-readyallowline. -
Add probes:
solution/probe-N.shplus a[[metadata.miroir.probes]]entry withharmand a reward bound. Run the check job untilmiroir checkexits 0:harbor run -c check.yaml --job-name gate miroir check --tasks tasks jobs/gate
A probe that earns too much means the spec is too weak: fix the spec. A probe whose calls fail
proves nothing: miroir check fails a solution that exits non-zero.
Rules
- Only
exposeports listen off loopback. Bind datastores and everything else to 127.0.0.1; the boot refuses any other TCP listener. - Read
after."<t>",before."<t>"andanswer, not the JSON inchanges. - Let
allowdo row scope. What it forbids needs no gate. - A check that doing nothing satisfies is a gate: the null run must score 0.
- Probes declare
harmand a reward bound, and every HTTP call in a solution or probe usescurl -fsS, or asserts the status it expects. - Never weaken a probe or the reference solution to make validation pass.
environment/is the same bytes in every task of a world; nothing per task reaches the world.- Bump
[task].version: minor for the spec or the grader image, major for the instruction, the world or the environment, patch for solutions, probes and metadata. - Pin all three images by digest when publishing: the world,
miroir-mainandmiroir. - Answers go to
/logs/artifacts/answer.txt, as the instruction says.
Harbor mechanics
Harbor's own create-task
and publish skills and
its docs cover task directories, jobs, agents, regrades and
the Hub. Miroir's tasks follow them, with a separate verifier from the miroir image and a
collect hook in the world service.
Sponsors
Details
- Marketplace
- raphaelDkhn/miroir
- Category
- Community