Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Miroir

Miroir turns a product’s Docker image into a reinforcement-learning environment for agents.

You add a manifest and a few tasks to that image. Miroir then runs the real product, gives an agent its API, and grades what the agent did from what changed in the product’s database and from the emails and HTTP calls the product sent. examples/gitea does this for the stock Gitea image, with 144 tasks and the measurements that show it grades right.

How it works

At image build, miroir bake starts the product, runs your seed commands and keeps the resulting state as a pristine copy. Before every episode, a reset stops every process, restores that copy, moves every date forward so the data keeps its age, and starts the product again.

During an episode, the agent acts as a user of the product through tools: HTTP requests to the API, the API’s docs, the product’s own MCP tools, code in a sandbox, and submit. Emails and outbound HTTP calls land in local sinks. Grading then folds every row change into net changes, runs the task’s checks on them, and returns a reward from 0 to 1. A change the task does not allow counts as harm.

Agents connect over OpenEnv (a WebSocket) or MCP. The Python package has a client and adapters for TRL and verifiers.

Two programs

ProgramRunsDoes
miroir (Rust)inside the env imagebakes, resets, serves episodes, grades, checks, scrubs dumps
miroir (Python)on the hostclient, TRL and verifiers adapters, container pools, review, calibration

Both are called miroir. Inside the image it is always the Rust binary.

Quick start

Build the example env, check it, serve it and run one episode by hand. You need Docker with buildx, and uv for the Python part.

Build and check

From a clone of the repository:

docker buildx bake acme-crm-env
docker run --rm --network none acme-crm-env check

acme-crm-env is Acme CRM, a small sales CRM in fixtures/acme-crm, with Postgres, Redis, a web server, a worker and an MCP server. check replays every task’s reference run and ends with PASSED.

Serve

docker run --rm -d -p 127.0.0.1:8000:8000 -e MIROIR_TOKEN=secret acme-crm-env
curl http://127.0.0.1:8000/health

/health answers 200 once the env is ready. Every other route needs the token:

curl -H 'Authorization: Bearer secret' http://127.0.0.1:8000/acme-crm/splits
curl -H 'Authorization: Bearer secret' -H 'Content-Type: application/json' \
  -d '{"split": "train"}' http://127.0.0.1:8000/acme-crm/tasks

Run an episode

Install the client:

uv venv && source .venv/bin/activate
uv pip install miroir

Then play the pay-invoice task in Python:

from miroir import Session

session = Session.lease(["http://127.0.0.1:8000"], token="secret", wait_busy=False)
start = session.reset("pay-invoice")
print(start["instruction"])

step = session.step("api_request", {"method": "POST", "path": "/invoices/4001/pay"})
print(step["observation"]["result"]["status"])

outcome = session.finish()  # submits, then fetches the episode's record
print(outcome["reward"], outcome["metadata"]["checks"])
session.close()

The reward is 1: the invoice is paid, the payment provider was called once, and nothing else changed.

Concepts

Env
A product’s Docker image extended with Miroir, a manifest, and tasks. One container runs one episode at a time.

App
A product interface accessible to the agent or grader: an HTTP API, MCP server, database, or combination.

Persona
The identity the agent acts as. Its credentials and headers are automatically attached to every request.

World
A seeded snapshot of product data. Most envs have one, named default.

Bake
Seeds each world at image build time and saves its pristine state for future resets.

Reset
Restores a world to its pristine state, restarts the product, advances dates, and waits until it is ready.

Task
An agent instruction, grading checks, allowed changes, and a golden run.

Episode
One attempt at a task, from reset until submission, step or time limit, or crash.

Net change
A row-level difference between the initial and final state: inserted, updated (including changed columns), or deleted. Changes reverted before the end are ignored.

Effect
An outgoing email or HTTP request captured by a sink.

Check
A SQL query or command that scores an episode from 0 to 1. Weighted checks contribute to reward; gates must score 1.

Harm
An unauthorized state change, failed gate, or broken environment. Harm overrides the normal reward with harm_reward (0 by default).

Golden run
A sequence of tool calls that solves a task. miroir check replays it and requires a reward of 1.

Probe
A sequence of tool calls with an expected reward range, used to verify that incorrect behavior is graded correctly.

Episode database
A SQLite database containing an episode’s tool calls, effects, net changes, and answer. Checks can query it. See the reference.

Record
The output of a completed episode: tool calls, net changes, effects, grade, timings, and signature.

Signature
A hash of the final state. Episodes with identical final states share a signature, allowing review to group them.

Add Miroir to the image

An env is the product’s own image with three things added: the miroir binary, a manifest and a tasks directory. Miroir runs every process of the product itself, so the datastores go in the same image as the apps.

Dockerfile

FROM ghcr.io/raphaeldkhn/miroir:0.0 AS miroir

FROM your-product-image
USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends postgresql-15 tini \
 && rm -rf /var/lib/apt/lists/*
ENV PATH=/usr/lib/postgresql/15/bin:$PATH
COPY --from=miroir /miroir /usr/local/bin/miroir
COPY miroir.yaml /miroir/miroir.yaml
COPY tasks/ /miroir/tasks/
RUN install -d -o postgres -g postgres /var/lib/postgresql/data \
 && su postgres -c "initdb -D /var/lib/postgresql/data --auth=trust" \
 && miroir bake
EXPOSE 8000
ENTRYPOINT ["tini", "--", "miroir"]
CMD ["run"]

ghcr.io/raphaeldkhn/miroir holds one static binary, /miroir, tagged X.Y.Z and X.Y. Initialize each datastore’s data directory, owned by the user it runs as, before miroir bake seeds the data the manifest describes. fixtures/acme-crm/Dockerfile.miroir is a full example. Build it like any image:

docker build -f Dockerfile.miroir -t my-env .

Run Miroir under an init

A reset kills every process in the container but Miroir and PID 1, so Miroir refuses to run unless it is the entrypoint. Use tini (or docker run --init, dumb-init, catatonit). If Miroir itself is PID 1, it runs but warns: the orphans a reset leaves are never reaped.

Run processes as non-root users

Give every process a user in the manifest. A process that runs as root fails check, since it could read the tasks’ checks and golden runs. Non-root users also let Miroir find the state to restore on its own.

Report the product’s version

Set MIROIR_ENV_VERSION in the image, such as to the product image’s tag. /metadata reports it, so you know which build an episode ran on.

ENV MIROIR_ENV_VERSION=ghcr.io/acme/crm:1.4.0

Write the manifest

/miroir/miroir.yaml tells Miroir what to run, what to restore and how to reach the product. This page walks through the manifest of the example CRM. Every field is in the manifest reference.

miroir: 1
name: acme-crm
description: Acme CRM, a sales CRM for small teams

processes:                          # started in this order, datastores first
  - {name: db, command: [postgres, -D, /var/lib/postgresql/data], user: postgres,
     datastore: true, ready: {tcp: 5432}}
  - {name: web, command: [node, dist/server.js], user: node, cwd: /app,
     ready: {http: "http://127.0.0.1:3000/healthz"}}
  - {name: worker, command: [node, dist/worker.js], user: node, cwd: /app}

env:                                # for every process and command
  DATABASE_URL: postgres://postgres@127.0.0.1:5432/crm
  SMTP_URL: smtp://127.0.0.1:2525
  STRIPE_API_BASE: http://127.0.0.1:9000/stripe

bake:                               # create the seed data, with only the datastores up
  - [createdb, -h, 127.0.0.1, -U, postgres, crm]
  - [node, dist/migrate.js]
  - [node, dist/seed.js]

state: [/var/lib/postgresql/data, /app/uploads]

apps:
  crm:
    api: {base_url: "http://127.0.0.1:3000", openapi: /app/openapi.yaml}
    database: {url: "postgres://postgres@127.0.0.1:5432/crm"}

personas:
  sales_manager:
    description: Dana Lee, sales manager at Acme (dana@acme.test)
    headers: {crm: {Authorization: Bearer seed-token-dana}}

sinks: {smtp: 2525, http: 9000}

quiet:
  command: [sh, -c, 'test "$(redis-cli llen bull:email:wait)" = 0']

Processes

Miroir starts the processes in order and waits for each ready probe before the next: a loopback TCP port, or an http:// URL that answers 2xx or 3xx. Mark the datastores with datastore: true and list them first. During a reset they run alone while the data is restored and its dates are moved. A datastore needs no durability, since each reset restores its files: run Postgres with -c fsync=off -c synchronous_commit=off -c full_page_writes=off to skip the fsyncs of each commit and checkpoint.

Bake and seed

bake commands create the seed data while only the datastores run. seed commands run after the apps start, for data that is easier to create through the product, such as through its API. Both get MIROIR_WORLD, the name of the world being baked.

State

state lists the directories each reset restores: the datastores’ data, uploads, caches. Leave it out and Miroir restores every path the processes’ users can write.

A file that changes outside the state lets one episode see another. check fails when that happens, and a running env refuses resets once it finds such a file.

Apps

Each app has an api, a database, an MCP server, or several.

  • api.base_url is where the agent’s requests go. api.openapi is the spec api_docs serves.
  • api.omit lists keys to drop from the API’s JSON answers before the agent sees them, such as links and avatars repeated in every object. Each answer’s tokens stay in the agent’s context for the rest of the episode, and in every training sample. A key matches at any depth; parent.key matches only in an object held under parent, so head.repo drops a pull request’s copy of its repository and keeps an activity’s repo. Braces give alternatives: {user,assignee}.created drops when a user’s account was made, and keeps when a commit was.
  • database.url is where grading reads net changes and runs checks. Connect as a user that can create triggers: bake installs triggers that log every row change.
  • database.ignore lists tables, or table.columns, whose changes never count, such as a last_used_at the product touches on every request.

An env with several apps names the app in each request and check.

Personas

A persona is the user the agent acts as. Its headers go on every request to that app, and win over headers the agent sends. Tasks pick a persona; with one persona, every task uses it.

Sinks

The sinks are a local SMTP server and HTTP server that record what the product sends. Point the product’s outbound settings at them, as SMTP_URL and STRIPE_API_BASE do above.

Quiet

Grading must wait for background work, such as a queued email, to finish. quiet.command exits 0 when the product is idle; Miroir waits until it passes twice in a row, for up to timeout_s (30 s). Without it, Miroir waits one second.

What bake does

Bake validates the tasks already in /miroir/tasks, so a broken task file fails the build before the seeding. Then, for each world:

  1. Start the datastores and wait until each database answers.
  2. Run the bake commands.
  3. Start the apps and wait for quiet.
  4. Run the seed commands and wait for quiet.
  5. Install the triggers that log row changes.
  6. Stop everything and move the state to /miroir/pristine/<world>.

Last, it validates every task again, including those a seed wrote: see Generate tasks in the seed.

What a reset does

  1. Kill every process.
  2. Restore the state, copying only the files that changed, and empty /tmp, /var/tmp and /dev/shm.
  3. Start the datastores and move every date forward by the days since bake. See Dates.
  4. Run the task’s setup SQL, if any.
  5. Start the apps and wait for quiet.
  6. Clear the change log and the episode database.

Write tasks

Each YAML file in /miroir/tasks/ is a task. Its id is the file name, so tasks/pay-invoice.yaml is the task pay-invoice.

instruction: >
  The customer on invoice INV-04001 asked us to charge their card on file today. Take the
  payment through the CRM.
max_steps: 20
checks:
  - name: paid
    weight: 0.6
    sql: SELECT status = 'paid' AND payment_intent = 'pi_test' FROM invoices WHERE number = 'INV-04001'
  - name: charged_once
    weight: 0.4
    db: episode
    sql: |
      SELECT count(*) = 1 FROM effects
      WHERE kind = 'http' AND json_extract(data, '$.path') = '/stripe/v1/payment_intents'
  - name: only_invoice_4001
    gate: true
    db: episode
    sql: SELECT count(*) = 0 FROM changes WHERE tbl = 'invoices' AND json_extract(pk, '$.id') <> 4001
allowed_changes:
  - {table: invoices, op: update, columns: [status, paid_at, payment_intent]}
golden:
  - {tool: api_request, arguments: {method: GET, path: "/invoices?number=INV-04001"}}
  - {tool: api_request, arguments: {method: POST, path: /invoices/4001/pay}}
  - {tool: submit, arguments: {answer: "Charged INV-04001."}}
probes:
  - name: charges-another-customer-too
    steps:
      - {tool: api_request, arguments: {method: POST, path: /invoices/4001/pay}}
      - {tool: api_request, arguments: {method: POST, path: /invoices/4020/pay}}
      - {tool: submit}
    max_reward: 0

Checks

A check is one of three things:

KindRunsScores
sqlon the app’s database, read-onlythe query’s single value
sql with db: episodeon the episode database (SQLite)the query’s single value
commandin the env, as a commandwhat it prints on exit 0 (1 if nothing), else 0

A query returns one value: a boolean, or a number from 0 to 1. NULL scores 0.

The episode database holds the net changes (changes), the emails and HTTP calls (effects), the agent’s tool calls (actions) and the submitted answer. Query it to check what the product sent, or which rows changed.

Each check has either a weight or gate: true:

  • The weights add up to 1. They give partial credit.
  • A gate must score 1, or the episode counts as harm. Use gates for what must not happen.

Allowed changes

allowed_changes lists the net changes the task may make. Any other change is harm.

allowed_changes:
  - {table: invoices, op: update, columns: [status, paid_at, payment_intent]}
  - {table: notes, op: insert}

op is insert, update, delete, truncate or schema. columns limits an update to those columns. A task that changes nothing has allowed_changes: []. Set any_change: true instead to allow every change.

Golden run

golden is a list of tool calls that solves the task, ending with submit. miroir check replays it from a fresh reset and requires a reward of 1.

Answers

A task can ask a question. The agent puts its answer in submit, and a check compares it:

instruction: How many of Northwind Traders' open invoices are past their due date?
answer: integer
checks:
  - {name: answer, weight: 1, db: episode, sql: "SELECT value = '3' FROM answer"}
allowed_changes: []
golden:
  - {tool: api_request, arguments: {method: GET, path: "/invoices?contact_id=101&overdue=true"}}
  - {tool: submit, arguments: {answer: "3"}}

answer puts the submitted text in a normal form, so equal answers compare equal:

FormAcceptsStored as
integera whole number42
idsids separated by commas or spacessorted, deduplicated, 12,15,18
dateYYYY-MM-DDthe date moved back to how the task file writes it

An answer that doesn’t fit the form is an invalid_args error, and the agent can submit again.

Probes

A probe is a run whose reward must stay within max_reward or min_reward. Write one for each plausible wrong solution. Probes go in the task, or in tasks/probes/<task-id>.yaml as a list, which is where miroir review adds them.

Splits

split is train (the default), validation or test. Clients pick a split when they list or draw tasks.

Generate tasks in the seed

Checks name rows by the ids the database gave them, which exist only once the seed has run. A seed command can write the task files itself, to /miroir/tasks, from the ids it reads back: bake validates them after the seed, and fails the build if one doesn’t. A generator that plants the same kinds of work many times, with different rows and answers, gives many tasks per kind, which training needs. Keep the generator deterministic, so every bake writes the same tasks.

examples/gitea writes 144 tasks this way: twelve kinds of work, four times in each of three worlds.

Other fields

persona, world, max_steps (50 by default), setup (SQL run at reset), harm_reward, null_max, and the fields of clocks and coworkers are in the task reference.

Tips

  • Check the end state, not the calls the agent made: there are many ways to do a task.
  • Gate the changes that must not happen, such as another customer charged.
  • Compare a whole answer. A check that looks for the right answer inside a longer one rewards listing guesses; check tests for that.

Grading

When an episode ends

EndingWhen
submitthe agent calls submit
max_stepsthe agent has made max_steps tool calls
max_secondsa call comes after the reset’s max_seconds ran out
crasha process of the product exited
voidMiroir lost part of the record during a wait

The episode’s metadata gives the ending as termination.

What grading does

  1. Wait for quiet, so background work has landed.
  2. Read each database’s change log and fold it into net changes. Ignored tables and columns drop out. Rows of a table without a primary key count as a multiset. A table created, dropped or reshaped is a schema change.
  3. Store the net changes in the episode database.
  4. Run the checks. App database checks read the same snapshot as the net changes.
  5. Compare the net changes with allowed_changes. This is the scope gate.

The reward

A net change outside allowed_changes, or a gate below 1, makes the episode harm, which earns harm_reward: 0 by default, and as low as -1. Otherwise the reward is 1 when every check scores 1, and when one doesn’t, the sum of each weighted check’s weight times its score.

With the pay-invoice task, scores of 1 for paid and 0 for charged_once earn 0.6 × 1 + 0.4 × 0 = 0.6. An agent that also pays another invoice fails the only_invoice_4001 gate, and earns harm_reward: 0.

Faults

An episode that breaks the env earns harm_reward, and its metadata’s fault says why:

  • The quiet command never passed before grading.
  • A check failed: a SQL error, more than 10 s, or a value that is neither a number nor a boolean.
  • The change log grew past MIROIR_LOG_BUDGET_MB (1024 by default).
  • The emails and HTTP calls passed 1 GiB, or the agent’s code sent more than 64 MiB of requests.
  • A process crashed. The metadata’s crashed names it.

No reward

When Miroir itself fails, such as losing part of the record, the reward is null and the metadata’s invalid says why. The adapters drop these rollouts rather than train on them.

Reading the result

The last step returns the reward, done: true and the metadata, abridged here:

{
  "task_id": "pay-invoice",
  "success": false,
  "harm": false,
  "checks": [
    {"name": "paid", "score": 1.0},
    {"name": "charged_once", "score": 0.0},
    {"name": "only_invoice_4001", "gate": true, "score": 1.0},
    {"name": "scope", "gate": true, "score": 1.0}
  ],
  "out_of_scope": [],
  "out_of_scope_count": 0,
  "termination": "submit"
}

Every field is in Episode results.

Check the env

miroir check tells you whether the env grades reliably. Run it after every change to the manifest or the tasks, until it passes:

docker run --rm --network none my-env check
miroir check: acme-crm
static                       pass
users                        pass
idle                         pass
mcp                          pass (3 tools)
task                         golden null  repeat  reset  writes golden statuses
count-overdue-invoices       pass   pass  pass    pass   pass   200 200 ok
export-open-deals            pass   pass  pass    pass   pass   201 ok
pay-invoice                  pass   pass  pass    pass   pass   200 200 ok
reset p50 0.9 s, p95 1.07 s; grading p50 0.24 s, max 0.46 s
PASSED

A failed stage prints its reasons under the task, and the command exits non-zero.

Env stages

StagePasses when
staticthe manifest and every task load and validate
usersevery process has a user (write user: root to keep one as root)
idleresets a day and 400 days later work, and 30 s after a reset with no agent action leave no change, no effect and no crash
mcpthe app’s MCP server lists its tools (only with an MCP server)
sandboxthe sandbox reaches nothing of the env’s but its proxy (only with MIROIR_SANDBOX)

Task stages

StagePasses when
goldenthe golden run succeeds, and every call works: HTTP below 400, code exits 0, no tool error
nullan immediate empty submit earns at most null_max (0 by default), and every gate holds
repeattwo more golden runs earn the same reward and the same check scores
resetthe data after reset and setup hashes the same in all of these runs, and as in the first run checked of the same world and setup, time columns aside
writesno file changed outside the state directories
probeseach probe’s reward stays within its bounds
hedgesubmitting the golden answer among wrong guesses earns at most null_max
driftthe golden run earns the same when timestamps sit a day behind dates

hedge runs for tasks whose golden run submits an answer, unless the answer form is integer or date. drift catches checks that break depending on the time of day of the reset.

Options

OptionDoes
--jsonprint the full report as JSON
--world Wcheck only the tasks of world W
--mutatealso replay the golden run once without each of its calls

--mutate shows calls the run still succeeds without (reads, or checks too weak to notice), and calls whose removal still earns a reward.

With a sandbox

Tasks whose runs call run_code need a sandbox. sandbox/check.sh runs the check beside one, the two alone on an internal network. It uses the miroir-sandbox image, or the one SANDBOX_IMAGE names:

SANDBOX_IMAGE=ghcr.io/raphaeldkhn/miroir-sandbox:0.0 sandbox/check.sh my-env

Arguments after the image go to check, such as --json.

Several apps

An env can hold several apps, such as two offices’ CRMs and a ledger. Each app has its own API, database or both.

apps:
  east:
    description: the East office's CRM
    api: {base_url: "http://127.0.0.1:3000", openapi: /app/openapi.yaml}
    database: {url: "postgres://postgres@127.0.0.1:5432/east"}
  west:
    description: the West office's CRM
    api: {base_url: "http://127.0.0.1:3001"}
    database: {url: "postgres://postgres@127.0.0.1:5432/west"}
  ledger:
    database: {url: "postgres://postgres@127.0.0.1:5432/ledger"}
personas:
  sales_manager:
    description: Dana Lee in the East office, Alex Kim in the West
    headers:
      east: {Authorization: Bearer seed-token-dana}
      west: {Authorization: Bearer seed-token-alex}

fixtures/acme-apps is the full example.

Naming the app

Name app wherever several apps could be meant, and only there:

When several apps haveapp is required in
an APIapi_request and api_docs calls, golden and probe steps, event and reply requests
a databasesql checks, allowed_changes entries, coworker inboxes

Each app with an API then needs a description: the tools show it to the agent.

checks:
  - {name: won, weight: 0.5, app: east, sql: "SELECT status = 'won' FROM deals WHERE id = 1100"}
  - {name: noted, weight: 0.5, db: episode,
     sql: "SELECT count(*) = 1 FROM changes WHERE app = 'west' AND tbl = 'notes'"}
allowed_changes:
  - {app: east, table: deals, op: update, columns: [status, stage, updated_at]}
  - {app: west, table: notes, op: insert}
golden:
  - {tool: api_request, arguments: {app: east, method: PATCH, path: /deals/1100, body: {status: won}}}
  - {tool: api_request, arguments: {app: west, method: POST, path: /deals/1100/notes, body: {text: East closed it.}}}
  - {tool: submit}

With several databases, the app column of the changes table names each change’s app. A command check gets the database of its app as MIROIR_DATABASE_URL.

Rules

  • Two apps can’t name the same database. Give the second app only an api; its changes count under the first.
  • Two MySQL databases on one server can’t be told apart. Give each its own server.
  • Only one app may have an MCP server.
  • A task’s setup runs on the only database, so it can’t be used with several.
  • In the sandbox, each app’s API is at $API_<APP>: the name in capitals, with - as _. Two apps can’t map to the same variable.

Worlds

A world is a seed snapshot. Most envs have one, default. List several to train on different data with the same product:

worlds: [north, south]

Bake

Bake seeds each world in turn, each from the same unbaked state, and keeps a pristine copy of each. The bake and seed commands get MIROIR_WORLD, so a seed script can branch on it:

const seed = SEEDS[process.env.MIROIR_WORLD];

World names are lowercase letters, digits, _ and -, starting with a letter or a digit.

Tasks

With several worlds, every task names its world, and each reset restores that world:

world: north
instruction: Products 4 and 9 are sold out. Set the stock of each to 25.

Hold whole worlds out for test

With several worlds, a world can’t have both test tasks and tasks of other splits. Keep some worlds for test only, so a test score comes from data training never saw.

Check one world

docker run --rm --network none my-env check --world north

A world can also come from a snapshot taken at a known time, such as an imported production dump. See captured worlds.

Dates

Seed data has dates: an invoice due last week, a deal updated yesterday. Each reset moves every date forward by the time since bake, so the data keeps its age. An invoice due a week before bake is due a week before today.

What moves

Timestamps move by the whole days since the anchor, rounded down, so their time of day stays. Dates move by the calendar days (UTC) since the anchor’s date.

Miroir moves every date and timestamp column of every app database, and leaves alone:

  • values from 9000-01-01 on, such as a 9999-12-31 that means “never”;
  • the columns in database.time.exclude, such as birthdays.

Integer columns that hold Unix time don’t look like time. List them in database.time.epoch as table.column globs, with their unit, s or ms:

apps:
  crm:
    database:
      url: postgres://postgres@127.0.0.1:5432/crm
      time:
        exclude: [contacts.birthday]
        epoch: {deals.synced_unix: s, "events.*_ms": ms}

The reset observation’s now is the time the episode starts, and the adapters tell the agent today’s date.

The anchor

time.anchor is when the seed data is dated. The default, bake, is when bake ran. Set an RFC 3339 instant when the seed data is written for a fixed day:

time:
  anchor: "2026-01-15T09:00:00Z"

Dates outside the databases

Miroir moves only database columns. For dates elsewhere, such as files or a search index, set time.hook: a command each reset runs after moving the databases, before the apps start. It gets the shift as MIROIR_SHIFT_DAYS (whole days, for timestamps) and MIROIR_SHIFT_DATE_DAYS (calendar days, for dates). A failing hook fails the reset.

time:
  hook: [node, dist/shift-index.js]

An env with a hook can’t have clock tasks or captured worlds: those move only the databases.

Captured worlds

A world can be a snapshot taken at a known time, such as a production dump. List when it was taken, and bake moves its dates from then to the anchor:

worlds: [default, prod-2026-03]
time:
  captured: {prod-2026-03: "2026-03-02T00:00:00Z"}

Answers that are dates

A task with answer: date writes dates as they were at bake. Miroir moves the agent’s answer back by the same shift before storing it, so SELECT value = '2026-01-20' FROM answer keeps working on any day.

Clock and events

Some tasks need time to pass: “When the buyer signs, mark the deal won within two hours.” A task has a clock when it has events, or a check with by. Its agent then gets the wait tool.

instruction: >-
  Priya Shah notes deal 1100 when its buyer signs. Within two hours of her note, set the
  deal's stage to won. Use wait to let time pass; it ends early when something happens.
events:
  - name: signed
    at: 90
    headers: {crm: {Authorization: Bearer seed-token-priya}}
    request: {method: POST, path: /deals/1100/notes, body: {text: The buyer signed.}}
checks:
  - name: won_in_time
    weight: 1
    by: 210
    db: episode
    sql: >-
      SELECT EXISTS (SELECT 1 FROM changes d, changes n
        WHERE d.tbl = 'deals' AND json_extract(d.after, '$.stage') = 'won'
          AND n.tbl = 'notes' AND n.op = 'insert' AND json_extract(n.after, '$.author_id') = 12
          AND json_extract(d.after, '$.updated_at') >= json_extract(n.after, '$.created_at'))
allowed_changes:
  - {table: deals, op: update, columns: [stage, updated_at]}
  - {table: notes, op: insert}
golden:
  - {tool: wait, arguments: {minutes: 600}}
  - {tool: api_request, arguments: {method: PATCH, path: /deals/1100, body: {stage: won}}}
  - {tool: submit}

wait

wait takes minutes, from 1 to 10080 (a week). Everything in the databases moves that many minutes into the past, as if the time had gone by, while the apps keep reading the real clock. The wait ends early at the first event. It returns how long it lasted, waited_minutes, and the minutes since the task began, elapsed_minutes.

Events

An event is a request sent at clock minute at, as someone other than the agent. request takes app, method, path and body; headers are the sender’s, by app. If an event’s request fails or answers 5xx, the episode has no reward.

Milestones

A weighted check with by is scored when the clock reaches that minute, and keeps that score. Above, the deal must be won by minute 210: two hours after the note at minute 90. Gates can’t take by, since a gate says what must not happen by the end.

Before grading

The clock runs to the last event or milestone before grading, so an agent that submits early still meets every event, and every milestone gets a score. The episode’s metadata has clock: the minutes elapsed, and each event with its minute and status.

Rules

  • A wait step in a golden run or probe takes exactly minutes.
  • Clock minutes go up to 525,600, a year.
  • A task with a clock can’t take a date answer, and can’t run in an env with time.hook.

Coworkers

A coworker is a colleague a model plays. The agent writes to them in the product, such as in a note that mentions them. Miroir reads their inbox, has a model answer as them, and posts the answer in the product as them.

instruction: Ask Priya Shah (priya) in a note on deal 1100 which stage it is really at, then set it.
coworkers:
  - name: priya
    description: Priya Shah, account executive at Acme (priya@acme.test)
    script: Deal 1100 fell back to qualified last week, since the buyer asked to re-scope it.
    headers: {crm: {Authorization: Bearer seed-token-priya}}
    inbox:
      sql: >-
        SELECT json_agg(json_build_object('id', id, 'text', text, 'deal', deal_id) ORDER BY id)
        FROM notes WHERE author_id = 1 AND text ~* '@priya\M'
    reply: {method: POST, path: "/deals/{deal}/notes", body: {text: "{text}"}}
golden:
  - {tool: api_request, arguments: {method: POST, path: /deals/1100/notes, body: {text: "@priya which stage is deal 1100 at?"}}}
  - {tool: coworker_reply, arguments: {coworker: priya, text: "Qualified: they asked to re-scope."}}
  - {tool: api_request, arguments: {method: PATCH, path: /deals/1100, body: {stage: qualified}}}
  - {tool: submit}

Fields

FieldWhat
name1 to 64 lowercase letters, digits, _ or -
descriptionwho they are
scriptwhat they know, and how they act
headerstheir own headers, by app, which their replies send
inbox.sqla query on the app’s database that returns a JSON array of messages, each with an id and a text
inbox.appthe database to query, when several apps have one
replythe request that posts an answer: app, method, path, body

In reply, {text} is the answer, and any other {field} comes from the last message the inbox returned. Above, {deal} comes from the message’s deal.

How a turn goes

  1. Messages already in the inbox at reset are never answered.
  2. The client asks for turns with a coworkers frame. Miroir reads each inbox. A coworker with new messages owes a reply, and their turn carries the chat to answer: a system prompt made from their description and script, then the last 20 messages.
  3. The client sends that chat to a model and returns the answer in a coworker_reply frame. Miroir posts it through reply, as the coworker.

Messages and answers are cut at 4,000 characters. The adapters answer the owed turns between the agent’s calls. See the protocol.

Clients must opt in

A reset draws tasks with coworkers only when it says coworkers: true, which tells Miroir the client answers them. Naming such a task without it is an error. Both adapters opt in once they have a coworker model, any OpenAI-compatible chat endpoint:

  • TRL: environment_factory(..., coworker=CoworkerModel(base_url, model, api_key)), and dataset(..., coworkers=True).
  • verifiers: --env.taskset.coworker_model, --env.taskset.coworker_base_url and --env.taskset.coworker_api_key_var.

Golden runs

A coworker_reply step, with a coworker and a text, stands for the coworker’s answer. check posts that text as their reply. Each coworker needs one in the golden run, after the call that reaches them.

Code sandbox

run_code lets the agent run bash, for work that would take many API calls, such as updating two hundred rows. The code runs in a container of its own, the sandbox, and reaches the apps only through Miroir, as the persona.

Start a sandbox

The sandbox image is ghcr.io/raphaeldkhn/miroir-sandbox: Debian with python3 (and requests), curl and jq, running miroir sandbox. Put it and the env on a network of their own, and point the env at it with MIROIR_SANDBOX:

docker network create --internal -o com.docker.network.bridge.inhibit_ipv4=true ep1
docker run -d --rm --name ep1-sandbox --network ep1 --network-alias sandbox \
  --read-only --tmpfs /work:exec,size=256m --tmpfs /tmp:exec,size=256m \
  --pids-limit 256 --memory 1g --security-opt no-new-privileges \
  ghcr.io/raphaeldkhn/miroir-sandbox:0.0
docker create --rm --name ep1 -p 127.0.0.1::8000 -e MIROIR_TOKEN \
  -e MIROIR_SANDBOX=http://sandbox:8000 my-env
docker network connect ep1 ep1
docker start ep1

python/tests/docker.sh does this for pools. The env serves the sandbox’s requests on port 8001.

Before it reports healthy, the env probes the sandbox. The sandbox must reach no port of the env’s but the proxy and the env’s server, and must not share the env’s network namespace. Miroir warns if the sandbox can reach the internet.

What the agent gets

Clients pick the code surface to get run_code in place of api_request. Inside the sandbox, each app’s API is at $API_<APP>, such as $API_CRM for the app crm:

curl -s "$API_CRM/deals?status=open" | jq length

Requests there act as the persona and take the paths api_docs lists. Each URL works only during the call it was given to. The code’s requests are recorded in actions, with via set to run_code, and they count in grading like any other.

run_code returns exit_code and output (stdout and stderr together).

Limits

LimitValue
one call60 s
output returned64 KiB
command1 MiB
a request or answer body8 MiB
all requests of an episode’s code64 MiB, past which the episode faults

Files the code writes in its workspace last until the episode ends. Processes stop when the call returns.

Check with a sandbox

Golden runs and probes that call run_code need a sandbox. Run the check with sandbox/check.sh.

MCP servers

If the product has an MCP server, the agent can use its tools in place of the HTTP API. Name the server under its app:

apps:
  crm:
    api: {base_url: "http://127.0.0.1:3000", openapi: /app/openapi.yaml}
    mcp: {url: "http://127.0.0.1:3100/mcp"}
    database: {url: "postgres://postgres@127.0.0.1:5432/crm"}

The URL must be plain http:// on loopback. Only one app may have an MCP server, and the manifest still needs an app with an api.

How the agent uses it

Clients pick the mcp surface: the env’s MCP endpoint at /mcp?surface=mcp then lists the server’s tools, plus submit and, for tasks with a clock, wait. Miroir calls the server with the persona’s headers for that app, and records each call in actions like any other. Over the WebSocket, the agent can call the server’s tools by name.

Miroir lists the server’s tools once, and opens a new MCP session after every reset. A tool can’t be named like one of Miroir’s own: api_request, api_docs, submit, run_code, wait or coworker_reply.

In tasks

Golden runs and probes can call the server’s tools:

probes:
  - name: through-the-crm-mcp-server
    steps:
      - {tool: get_deal, arguments: {deal_id: 1100}}
      - {tool: update_deal, arguments: {deal_id: 1100, status: won, stage: won}}
      - {tool: submit, arguments: {answer: "Deal 1100 is won."}}
    min_reward: 1

check lists the server’s tools in its mcp stage, and fails if it lists none.

Sinks

Products send emails and call outside services, such as a payment provider. In an env, the sinks stand in for the outside world: a local SMTP server and HTTP server that record each email and call as an effect, which checks can query.

env:
  SMTP_URL: smtp://127.0.0.1:2525
  STRIPE_API_BASE: http://127.0.0.1:9000/stripe
sinks:
  smtp: 2525
  http: 9000
  responses:
    "POST /stripe/v1/payment_intents": {status: 200, json: {id: pi_test, status: succeeded}}

Point the product’s outbound settings at the sinks, as the env above does. Both listen on 127.0.0.1.

SMTP

The SMTP sink accepts every message, with or without login, and records it as an email effect: from, to, cc, bcc, subject, text and html.

HTTP

The HTTP sink records each request as an http effect: method, path, query, headers (without Authorization) and body, parsed when it is JSON. It answers 200 and {}, unless a canned response matches.

responses keys are /path or METHOD /path, and a trailing * matches a prefix. An exact path beats a prefix, a longer prefix beats a shorter one, and a key with a method beats one without. A response has a status (200 by default), a json or a body, and headers.

Checking effects

- name: emailed
  weight: 0.5
  db: episode
  sql: |
    SELECT count(*) = 1 FROM effects
    WHERE kind = 'email' AND json_extract(data, '$.to[0]') = 'marcus@acme.test'
      AND json_extract(data, '$.subject') = 'Deal 2001 is now yours'

The shapes of both effects are in the episode database reference.

Limits

A message can be up to 25 MiB, with up to 1,000 recipients. An episode’s effects can take up to 1 GiB, past which the episode faults.

Warning

The sinks see only what the product sends them. Run the env on an internal network: other outbound calls are neither recorded nor blocked. Miroir warns at start when it can reach the internet.

Serve an env

docker run --rm -d -p 127.0.0.1:8000:8000 -e MIROIR_TOKEN=secret my-env

miroir run, the image’s default command, restores the first world and serves on port 8000. Its log says env ready once /health answers 200.

One container runs one episode at a time, and holds one session: a second WebSocket is refused with CAPACITY_REACHED. For parallel rollouts, run several containers, such as with a pool.

Routes

RouteWhat
GET /health{"status": "healthy", "leased": false}, or 503 while the env can’t serve
GET /wsthe OpenEnv session; see Protocol
POST /mcpMCP over JSON-RPC; see Protocol
POST /episode, POST /episode/endstart and end an episode without a WebSocket; see Protocol
GET /metadataname, description, version, miroir_version, manifest_hash, tasks_hash
GET /schemaJSON schemas of the frames
GET /openapi.jsonthese routes
GET /list_environmentsthe env’s name, in a list
GET /{name}/splitsthe splits that have tasks
POST /{name}/tasksa split’s tasks: {"split": "train"}
POST /{name}/num_taskshow many tasks a split has: {"split": "train"}
POST /{name}/taskone task: {"split": "train", "index": 0}
POST /{name}/task_rangea range: {"split": "train", "start": 0, "stop": 10}

/health answers 503 before the first restore, while the env is broken, while its sandbox doesn’t answer, and once it is shutting down. leased says whether a session holds the env.

A listed task has id, split, world, instruction, persona (name and description), max_steps and task_hash, plus system_prompt when the manifest has one and coworkers when the task has some.

Settings

Besides MIROIR_TOKEN and MIROIR_AGENT_TOKEN, the env reads MIROIR_PORT (8000 by default), MIROIR_SANDBOX (a sandbox for run_code), MIROIR_LOG_BUDGET_MB and MIROIR_ENV_VERSION. See Environment variables.

Security

  • Set MIROIR_TOKEN. Clients send it as Authorization: Bearer <token>; /mcp also takes ?token=. The product’s processes don’t see it.
  • When an agent calls /mcp itself, as over HTTP episodes, give it MIROIR_AGENT_TOKEN instead: a second token that opens /mcp alone, so the agent can’t end its episode, start another or read the task listings. It needs MIROIR_TOKEN set, and must differ from it.
  • Requests that carry an Origin header, as web pages send, are refused.
  • Publish the port on 127.0.0.1, and run the env on an internal network. Calls the product makes past the sinks are neither recorded nor blocked.

Recovery

When a process crashes or a reset fails, /health turns 503. While no session holds the env, Miroir restores it every 10 seconds, backing off to 5 minutes, until it works again.

When files change outside the state directories, one episode could see another, so the env refuses every reset from then on. Replace the container, and add the files to state.

Stop

docker stop sends SIGTERM. Miroir stops the processes, giving them 30 seconds, and exits.

Protocol

Clients drive episodes over a WebSocket at /ws, in OpenEnv frames. Agents can also call the tools over MCP at /mcp, and a harness can start and end their episodes over HTTP. The Python client speaks the WebSocket for you.

Frames

Every frame is a JSON object with a type and, for most, data:

{"type": "reset", "data": {"task_id": "pay-invoice"}}
FramedataReply
resetwhich task, and options (below)observation: the task the agent starts on
stepan action (below)observation: the tool list or the call’s result
statenonestate: episode_id, step_count, task_id, done, reward, success
recordepisode_id, optionalrecord: the finished episode’s record
coworkers{}coworkers: the turns coworkers owe
coworker_replycoworker, textcoworker_reply: the app’s HTTP status
closenonethe server closes the socket

An error comes back as {"type": "error", "data": {"code": "...", "message": "..."}}. The codes are INVALID_JSON, VALIDATION_ERROR, UNKNOWN_TYPE, EXECUTION_ERROR, SESSION_ERROR and CAPACITY_REACHED.

Reset

FieldWhat
task_idthe task to run; wins over the others
splitthe split to draw from; train by default
indexthe split’s task at this index, in id order
seedthe split’s task at seed mod the number of tasks
episode_idan id for the episode, 1 to 255 characters; a UUID by default
max_secondsafter this many seconds, the next call ends the episode as it stands
coworkerstrue if the client answers coworkers

With neither task_id, index nor seed, the task is drawn at random. Draws leave out tasks with coworkers unless coworkers is true.

The reply:

{"type": "observation", "data": {
  "observation": {
    "task_id": "pay-invoice",
    "instruction": "The customer on invoice INV-04001 asked us to charge their card...",
    "persona": {"name": "sales_manager", "description": "Dana Lee, sales manager at Acme"},
    "now": "2026-11-10T09:30:00Z",
    "max_steps": 20,
    "metadata": {"reset_s": {"kill": 0.05, "restore": 0.1, "total": 0.9}}
  },
  "reward": null,
  "done": false
}}

Step

A step lists the tools or calls one:

{"type": "step", "data": {"type": "list_tools"}}
{"type": "step", "data": {"type": "call_tool", "tool_name": "api_request",
  "arguments": {"method": "GET", "path": "/invoices?number=INV-04001"},
  "metadata": {"episode_id": "..."}}}

The reply carries the observation, the reward and done:

{"type": "observation", "data": {
  "observation": {"tool_name": "api_request", "error": null, "metadata": {},
                  "result": {"status": 200, "headers": {"content-type": "application/json"},
                             "body": [{"id": 4001, "number": "INV-04001", "status": "open"}]}},
  "reward": 0.0,
  "done": false
}}

A failed call has result: null and an error with an error_type (invalid_args, execution_error, transport_error, tool_not_found or timeout) and a message. The agent can go on after an error.

The step that ends the episode has done: true, the reward, and the episode’s metadata. The reward is null when the episode could not be graded. See Grading.

Pass the reset’s episode_id in each call’s metadata: a call for an earlier episode is refused instead of acting on the current one. Arguments set to null are dropped.

Coworker frames

coworkers returns {"turns": [{"coworker": "priya", "messages": [...]}]}, where messages is a chat to send to a model: a system message, then user and assistant messages. Send the model’s answer back:

{"type": "coworker_reply", "data": {"coworker": "priya", "text": "It's qualified."}}

MCP

POST /mcp speaks MCP over JSON-RPC (protocol 2025-06-18 or 2025-03-26): initialize, ping, tools/list and tools/call. Its query string takes:

ParameterWhat
surfaceapi (default): api_request, api_docs, wait, submit; code: run_code in place of api_request; mcp: the app’s MCP tools, wait and submit. wait is listed only for tasks with a clock
episode_idthe episode the calls are for
tokenthe bearer token, for clients that can’t send headers

MCP calls step the same episode as the WebSocket session, or as POST /episode, which does the reset. A tools/call result is the step’s observation, with MCP’s content and isError, and done and reward.

Episodes over HTTP

A harness whose agent speaks MCP alone, such as Claude Code or Codex, can run an episode with two HTTP requests in place of the WebSocket session:

curl -X POST http://127.0.0.1:8000/episode -H 'Authorization: Bearer secret' \
  --json '{"task_id": "pay-invoice"}'
# The agent works through http://127.0.0.1:8000/mcp ...
curl -X POST http://127.0.0.1:8000/episode/end -H 'Authorization: Bearer secret'
RouteBodyAnswer
POST /episodea reset frame’s data; empty draws a taskthe reset’s observation, reward and done, and the episode_id
POST /episode/endnonethe episode’s record

POST /episode holds the env as a session does: until POST /episode/end, /health says leased, and a second POST /episode or a WebSocket session is refused. POST /episode/end submits for the agent if the episode still runs, as the Python client’s finish() does, then answers the record and frees the env. Unlike a session, which ends when its socket closes, the episode holds the env until someone ends it: a harness that stops first leaves it held, and POST /episode/end frees it. Tasks with coworkers need the WebSocket session, whose frames answer for them.

Errors answer {"detail": "..."}: 400 for data the reset refuses, 409 when the env is held, or when no episode started over HTTP is running, and 500 when the reset or the end fails.

Give the agent MIROIR_AGENT_TOKEN, not MIROIR_TOKEN: it opens /mcp alone, so the agent can’t end its episode or start another. See Serve an env.

Pools

A trainer runs many rollouts at once, and each needs a container of its own. miroir pool keeps a number of containers healthy and lists their URLs in a file, which the adapters read to lease a free container for each rollout.

export MIROIR_TOKEN=secret
miroir pool --size 8 --urls urls.txt -- python/tests/docker.sh my-env

This is the Python CLI, on the host. Size the pool to the rollouts in flight, plus a few spare. It prints ready: 8 of 8; start the trainer once every container is healthy.

The command

The command after -- starts or stops one container:

  • COMMAND start prints ID URL as its last line, such as 3f2a… http://127.0.0.1:49153.
  • COMMAND stop ID removes that container.

It runs with MIROIR_POOL set to the pool’s name, so it can label what it starts. python/tests/docker.sh is a full example: it starts the env alone, or beside a sandbox when SANDBOX_IMAGE is set, and passes MIROIR_TOKEN through.

What the pool does

  • Checks each container’s /health every 10 seconds.
  • Replaces a container that is not healthy 15 minutes after its start, that stops answering for a minute, or that stays unhealthy for 10 minutes.
  • Rewrites the URL file as containers come and go, one URL per line, with the container’s id after a #.
  • On SIGINT or SIGTERM, stops every container and removes the file.
  • On start, stops the containers an earlier pool on the same file left behind.

It gives up if no container ever becomes healthy, or if the first three starts all fail.

On Prime Intellect

examples/gitea/prime_sandbox.py runs each container as a Prime sandbox, from an image that prime images push built:

export MIROIR_TOKEN=$(openssl rand -hex 24)
miroir pool --size 32 --urls urls.txt -- \
  python examples/gitea/prime_sandbox.py prime/<you>/my-env:<tag>

Each sandbox has no egress and publishes port 8000 at https://8000-<sandbox-id>.sandbox-v2-prod.pinfra.io. Prime does not authenticate that URL, so MIROIR_TOKEN is all that guards the env, and the script refuses to start without it.

A sandbox is a VM, not a container, which changes two things:

  • Each reset kills every process but PID 1 and miroir, so miroir run needs a PID namespace of its own: the script starts it with unshare --pid --fork --mount-proc tini -- miroir run.
  • /run is mounted empty at boot, so a datastore can’t use a directory the image made there. Give it a socket elsewhere, or none, as the Gitea example does for Postgres.

Using the file

from miroir.trl import environment_factory

factory = environment_factory(urls_file="urls.txt", token="secret")
vf-run miroir-verifiers -m <model> --env.taskset.urls_file urls.txt --env.taskset.token_var MIROIR_TOKEN

The adapters reread the file at each lease, so replaced containers drop out on their own.

Run in Harbor

Harbor runs agents such as Claude Code and Codex on tasks, locally or in cloud sandboxes. miroir export harbor writes each task of an env as a Harbor task: the agent works the product through the env’s MCP server, and Miroir grades what it did.

Export

mkdir harbor
docker run --rm -v "$PWD/harbor:/out" my-env export harbor --image my-env:1.0 --out /out

--image names the env image as Harbor’s Docker will find it: a tag on the machine that runs Harbor, or an image in a registry it can pull. Each task goes in harbor/<split>/<task-id>/.

The export leaves out, and names, the tasks Harbor can’t run: tasks with coworkers, and tasks whose golden run calls a tool the agent won’t have, such as run_code or one of the product’s own MCP tools. The agent gets the api surface: api_request, api_docs, submit and, for tasks with a clock, wait.

Run

uv tool install harbor
harbor run -p harbor/test -a oracle                    # each reward should be 1
harbor run -p harbor/test -a claude-code -m <model>

The oracle agent replays each golden run through the MCP server, as an agent would. Each trial’s reward has two metrics: reward, the episode’s, and harm, 1 when the episode did harm, so a job’s means are its mean reward and its harm rate. The trial’s verifier/record.json is the episode’s record, which miroir review and miroir calibrate read:

miroir calibrate jobs/<job>/*/verifier/record.json --model <model> --out calibration.json

How a task runs

ServiceRunsHolds
mainthe agent, as the user agent; then the verifierthe agent token, in the agent’s MCP settings
appthe env image, on a network with no way outboth tokens
startPOST /episode for the task, before main startsthe control token

The verifier’s tests/test.sh calls POST /episode/end, which submits for the agent if it didn’t, and writes the reward. The agent’s token opens /mcp alone, so it can’t end its episode or start another; see MIROIR_AGENT_TOKEN in Serve an env.

Limits

  • Each task holds random tokens. They keep the agent from the env’s other routes, not whoever reads the task files, which also hold the golden runs.
  • The agent’s container reaches whatever the env listens on outside loopback. Keep the product and its datastores on 127.0.0.1, as the examples do, so the agent reaches only Miroir.
  • Run the tasks in Harbor’s default public network mode: the agent’s container joins the env’s network, which the no-network and allowlist modes take away or bypass.
  • The tasks are Docker Compose tasks: they run on Harbor’s docker environment and its cloud environments that run Compose, such as Daytona and Modal.

Python client

The miroir Python package (Python 3.11 or later) leases containers and runs episodes. The adapters build on it; use it directly for your own loop.

uv pip install miroir               # the client and the host CLI
uv pip install 'miroir[trl]'        # with the TRL adapter
uv pip install 'miroir[verifiers]'  # with the verifiers adapter

An episode

import datetime
import miroir
from miroir import Session

url, token = "http://127.0.0.1:8000", "secret"
task = miroir.tasks(url, "train", token)[0]

session = Session.lease([url], token, wait_busy=True)
try:
    start = session.reset(task["id"])
    today = datetime.date.fromisoformat(start["now"][:10])
    print(miroir.prompt(start, today))
    step = session.step("api_request", {"method": "GET", "path": "/invoices"})
    print(step["observation"]["result"]["status"])
    outcome = session.finish()
    print(outcome["reward"], miroir.metrics(outcome["record"]))
finally:
    session.close()

Session

CallDoes
Session.lease(urls, token=None, *, wait_busy, timeout_s=600)opens a session on a free, healthy container; urls is a list or the path of a URL file
reset(task_id, max_seconds=None, coworkers=False)starts an episode; returns the reset observation
step(tool, arguments)calls a tool; returns observation, reward and done
finish()submits if the episode still runs; returns reward, success, metadata and record
state()the env’s state frame
coworker_turns()the turns coworkers owe
coworker_reply(coworker, text)posts a coworker’s answer
close()frees the container

lease with wait_busy=False fails at once when every container is leased; otherwise it waits up to timeout_s.

Helpers

FunctionReturns
tasks(url, split="train", token=None)a split’s tasks, as the env lists them
tools(url, token=None, surface=None)the tools on a surface: api, mcp or code
prompt(task, today)the user prompt: the instruction, who the agent acts as, its step budget and today’s date
read_urls(path)the URLs of a file miroir pool writes
answer_coworkers(session, model)answers every owed coworker turn with a CoworkerModel
metrics(record)success, harm, the diagnostics and episode_s, to log
save_record(directory, record)appends a record to this process’s JSONL file there

CoworkerModel(base_url, model, api_key=None, temperature=None) is an OpenAI-compatible chat endpoint.

Errors

Everything raises MiroirError, with a code and a message. Codes include the env’s frame errors, NO_FREE_CONTAINER, CONNECTION_FAILED, CONNECTION_LOST, NOT_GRADED and COWORKER_FAILED.

TRL

miroir.trl plugs an env into TRL’s GRPOTrainer: a dataset of tasks, an environment factory whose methods are the agent’s tools, and a reward function.

uv pip install 'miroir[trl]'
from trl import GRPOConfig, GRPOTrainer
from miroir import read_urls
from miroir.trl import dataset, environment_factory, reward

urls = read_urls("urls.txt")  # as `miroir pool` writes it
trainer = GRPOTrainer(
    model="<model>",
    train_dataset=dataset(urls[0], token="secret"),
    environment_factory=environment_factory(urls_file="urls.txt", token="secret"),
    reward_funcs=reward,
    args=GRPOConfig(output_dir="out"),
)
trainer.train()

dataset

dataset(url, split="train", token=None, calibration=None, keep=("learnable",), coworkers=False)

A row per task, with task_id, instruction, persona and max_steps, and a prompt with the system message when the manifest has a system_prompt. With calibration, only the tasks whose class is in keep. Tasks with coworkers are left out unless coworkers=True.

environment_factory

environment_factory(urls=None, token=None, traces=None, *, harm_reward=None, urls_file=None, max_seconds=None, surface="api", coworker=None)

OptionWhat
urls or urls_filethe containers: a list, or a file miroir pool writes
tokenthe env’s MIROIR_TOKEN
tracesa directory to save each episode’s record in, for review and calibration
harm_rewardcaps the reward of a harmful episode, from -1 to 0
max_secondsa time limit per episode, 1 to 86,400
surfaceapi, or code for run_code in place of api_request
coworkera CoworkerModel that answers for coworkers

Each environment leases a container, and its public methods are the tools the env offers: api_request, api_docs, run_code, wait and submit. With several apps, api_request and api_docs take an app.

TRL makes per_device_train_batch_size * steps_per_generation environments per process, more for evaluation, and each needs a container of its own. Size the pool to match.

reward

reward finishes each episode and returns its reward, or None for an episode that could not be graded. With log_metric, it logs the means of miroir/success, miroir/harm, the call diagnostics and miroir/episode_s.

The prompt tells the agent today’s date. If the env’s date differs, as when an episode starts across midnight, the episode has no reward.

verifiers

The miroir-verifiers environment runs an env’s tasks under verifiers, for evaluation with vf-run and for training.

uv pip install 'miroir[verifiers]'
export MIROIR_TOKEN=secret
vf-run miroir-verifiers -m <model> \
  --env.taskset.urls_file urls.txt --env.taskset.token_var MIROIR_TOKEN

Each rollout leases a free container, waiting up to an hour for one, resets its task, and serves the env’s tools to the model over MCP. The reward is recorded as miroir, along with the metrics of the episode. A rollout that could not be graded fails with INVALID_GRADE instead of earning a reward.

Options

All under --env.taskset.:

OptionWhat
urls or urls_filethe containers: a JSON list of base URLs, or a file miroir pool writes
splitthe split to run; train by default
token_varthe variable that holds the env’s MIROIR_TOKEN
tokenthe token itself, for a run that passes no variables to the env
tracesa directory to save each episode’s record in
calibration, keepa calibration file, and the classes to run; ["learnable"] by default
harm_rewardcaps the reward of a harmful episode, from -1 to 0
surfaceapi (default), mcp for the app’s MCP tools, or code for run_code
max_secondsa time limit per episode, 1 to 86,400
coworker_modelthe model that plays coworkers
coworker_base_urlits OpenAI-compatible endpoint
coworker_api_key_varthe variable that holds its API key

Tasks with coworkers run only when coworker_model is set.

The number of rollouts in flight is capped at the number of URLs the file lists when the run starts.

Prime Intellect Hosted Training

Hosted Training runs the env on Prime’s servers, which install it from the Environments Hub. python/push_hub.py pushes it there, private, as <you>/miroir-verifiers: a wheel of the adapter and the client, versioned with the push’s time, since the Hub never reuses a version.

python python/push_hub.py

The containers must be reachable from Prime, such as a pool of Prime sandboxes. The training config names the taskset by its Hub id, env.taskset.id = "<you>/miroir-verifiers". Full-parameter runs pass neither prime train -e variables nor environment secrets to the env, so the pool’s URLs and token go in the config: with the source table last, append them to a copy and dispatch that:

{ cat rl.toml
  python -c 'import json, miroir; print("env.taskset.urls =", json.dumps(miroir.read_urls("urls.txt")))'
  echo "env.taskset.token = \"$MIROIR_TOKEN\""
} > rl.local.toml
prime train rl.local.toml

A config with several sources needs them under each, as the train and eval sources of examples/gitea/rl.toml do; examples/gitea/with_pool.py adds them.

The run’s config, and its logs (verifiers logs each rollout’s MCP URL, which carries the token), then hold the token: use a token for the pool alone, and delete the sandboxes when the run ends.

Review grades

Checks can be wrong: too strict, or too easy to fool. miroir review shows you how rollouts actually ended, asks whether each grade is right, and turns each wrong grade into a probe, so miroir check keeps it fixed.

miroir review traces/ --tasks fixtures/acme-crm/tasks

traces/ holds the records the adapters save with traces= (TRL) or --env.taskset.traces (verifiers): files, or directories of them.

How it goes

Rollouts that ended in the same state share a signature, so review groups them: one end state per task and signature, however many rollouts reached it. For each, it shows the rewards, the net changes and effects, the check scores and the calls of one example, then asks:

label: [c]orrect, should [f]ail, should [p]ass, [s]kip, [q]uit?
LabelMeansWrites
correctthe grade is rightthe label
should_failit earned too muchthe label, and a probe with max_reward set to the task’s null_max
should_passit earned too littlethe label, and a probe with min_reward: 1

The probe replays the example rollout’s own calls. It goes in tasks/probes/<task-id>.yaml, and the labels in tasks/probes/labels.jsonl, so labeled end states are not asked again. At the end, review prints how many grades you agreed with.

Fix the checks, then run miroir check: the new probes fail until the grade is right.

Options

OptionDoes
--label TASK@SIGNATURE=LABELlabel an end state without asking; repeat for more
--jsonprint the queue of unlabeled end states as JSON, and ask nothing

Rollouts that broke the env, or that have no grade, have no end state to label. Review counts them per task instead.

Calibrate tasks

A task teaches a model something only if its rollouts sometimes succeed and sometimes fail. miroir calibrate sorts tasks by how a model does on them, so training can skip the tasks it always solves and the tasks it never does.

Run several rollouts of each task, such as eight, with traces saved. Then:

miroir calibrate traces/ --model my-model-v3 --out calibration.json
task                      n  void   pass@1   pass@8   pass^8   reward      var     harm  class
count-overdue-invoices    8     0     1.00     1.00     1.00     1.00     0.00     0.00  solved
notify-new-owner          8     0     0.38     1.00     0.00     0.69     0.06     0.00  learnable
pay-invoice               8     0     0.00     0.00     0.00     0.00     0.00     0.25  out_of_reach

Classes

ClassWhen
learnablethe rewards vary
solvedevery rollout succeeds
out_of_reachevery rollout earns the same, short of success

A task with fewer than two graded rollouts gets no class. pass@k is the chance that at least one of k rollouts succeeds; pass^k, that all k do. -k sets k; by default it is the most rollouts any task has.

Use it

Give the file to an adapter to train on the learnable tasks only:

train_dataset = dataset(url, calibration="calibration.json")  # keep=("learnable",)
vf-run miroir-verifiers -m <model> --env.taskset.urls_file urls.txt \
  --env.taskset.calibration calibration.json

The file records each task’s task_hash. When a task file changes, the adapters refuse the calibration until you calibrate that task again.

Import and scrub dumps

Seed data made from production is realistic, but it holds people’s names, emails and secrets. miroir import turns production dumps into seed data: every such value becomes a keyed fake of the same shape, and the import fails if any original is left.

It runs inside the env image, which has the datastores:

mkdir -p in out
head -c 32 /dev/urandom > in/key
docker run --rm -v "$PWD/in:/in:ro" -v "$PWD/out:/out" my-env import \
  --dump crm=/in/crm.sql --scrub /in/scrub.yaml --key /in/key --out /out
OptionWhat
--dump APP=FILEa plain SQL dump of an app’s database; one per app
--scrub FILEthe scrub spec
--key FILEthe key, at least 32 bytes
--traces FILEproduction agent traces to scrub too; see Tasks from traces
--out DIRwhere to write the results

Dump one database per file: pg_dump without --create, or mysqldump without --databases. Mount the inputs and the output outside the env’s state directories and /tmp, as /in and /out above.

The scrub spec

The spec gives each text column a kind, by app and table:

apps:
  crm:
    contacts: {name: name, email: email, phone: phone, notes: text}
    users: {name: name, email: email, password_hash: secret}
    deals: {title: keep, stage: keep}
KindBecomes
nameeach word replaced by a fake word, keeping its case
emaila fake address, such as 3f9a1c2e4b7d8a90@1c2e4b7d.example
phonefake digits in the same format
secreta fake secret
textfree text with its emails, and the known names, phones and secrets, replaced
blankNULL
keepunchanged

List every column that is not a number, a truth value, a timestamp or a UUID; the import names the ones missing. name, email, phone and secret take text columns; text also takes JSON and arrays.

Keyed fakes

Under one key, an original always gets the same fake, and no two originals share one. Rows that matched in production still match, and dumps scrubbed apart stay consistent. Keep the key secret and out of the image: with it, anyone could test guesses of the originals.

Output

FileWhat
<app>.sqlthe scrubbed dump of each app
traces.jsonlthe scrubbed traces, with --traces
report.jsonrows scrubbed per column, fakes drawn, traces kept and left out

After scrubbing, the import scans every column for originals. If it finds any, it writes nothing and names the columns, so you can give them the right kind.

Load it at bake

Copy the scrubbed dump into the image, and load it in a bake command:

bake:
  - [createdb, -h, 127.0.0.1, -U, postgres, crm]
  - [psql, -h, 127.0.0.1, -U, postgres, -d, crm, -v, ON_ERROR_STOP=1, -f, /seed/crm.sql]

A dump is a snapshot from a known day. Declare it in time.captured, and bake moves its dates to the anchor. See Captured worlds.

Tasks from traces

Traces of a production agent show real requests and how they were solved. Three steps turn them into tasks:

  1. miroir import --traces scrubs them, along with the dumps.
  2. miroir draft writes a draft task for each trace.
  3. miroir derive replays each draft on the env and writes the checks its outcome holds to.

Trace format

A JSON object per line:

{"id": "t-1042", "consent": "support-terms-2026", "persona": "sales_manager",
 "request": "Charge the card on file for invoice INV-04001.",
 "calls": [{"tool": "api_request", "arguments": {"method": "POST", "path": "/invoices/4001/pay"}, "status": 200}],
 "answer": "Charged INV-04001."}
FieldWhat
idthe trace’s id: lowercase letters, digits, _ and -
consentthe basis on which the trace may be used; traces without one are left out
requestwhat the user asked
callsthe api_request and api_docs calls, each with its arguments and, optionally, the status it got
answerthe agent’s answer, if any
personathe persona that made the calls, if the manifest has several

Scrub

Import drops credential headers from the calls and scrubs every string as text. Name the argument fields that hold a name, an email, a phone or a secret under fields in the scrub spec, so their values are scrubbed everywhere they appear:

apps:
  crm: {contacts: {name: name, email: email}}
fields:
  contact_email: email

Draft

miroir draft out/traces.jsonl --world default --tasks tasks/

This writes tasks/<world>-<id>.yaml for each trace: the request as the instruction, the calls as the golden run, a placeholder check and any_change: true. --split sets the split, train by default. A trace that mentions a date is refused, since a reset moves the data’s dates but not the task’s text; rephrase it relative to today.

Derive

Serve the env with the drafts, then derive:

docker run --rm -d -p 127.0.0.1:8000:8000 -v "$PWD/tasks:/miroir/tasks:ro" my-env
miroir derive http://127.0.0.1:8000 out/traces.jsonl --world default --tasks tasks/

For each draft, derive:

  1. Replays the calls, and keeps those that work on the snapshot.
  2. Replays the kept calls again, from a fresh reset.
  3. Writes checks for what both replays agree on, a gate against any other change or effect, and the allowed_changes that cover them.

The finished task replaces the draft. Derive prints notes to review, such as a value the calls send that the request never shows, which an agent could not know. It refuses a trace whose calls worked in production but fail on the snapshot, or the reverse. --token-var names the variable that holds the env’s MIROIR_TOKEN.

Read each derived task, then run miroir check.

Manifest

The manifest is /miroir/miroir.yaml. Unknown fields are errors. A command is a list of strings, [program, arg, ...], run without a shell unless you call one.

Top level

FieldDefaultWhat
miroirrequiredformat version; must be 1
namerequiredletters, digits, ., _ and -; the env’s name in routes
descriptionrequiredwhat the product is; /metadata shows it
processesrequiredwhat Miroir starts, in order
env{}variables for every process and command Miroir runs
bake[]commands that create the seed data, with only the datastores up
seed[]commands run at bake once the apps are up
worlds[default]the worlds, each baked apart
statederivedthe directories each reset restores
appsrequiredthe apps, by name
personasrequiredthe users the agent can act as, by name
sinksnonethe sinks
quietnonethe command that tells when background work is done
timeanchor: bakehow the data’s dates follow the clock
system_promptnonea system prompt the task listings carry, for the adapters

Bake and seed commands get MIROIR_WORLD, and may run for up to an hour each.

processes[]

FieldDefaultWhat
namerequiredunique
commandrequiredthe command to run
userrootthe user it runs as; root fails check unless written user: root
cwdnonean absolute working directory
env{}variables for this process
datastorefalsestarted first, and alone while a reset restores and moves the data
readynonehow Miroir tells it is ready

Datastores come before every other process, and there is at least one.

ready takes exactly one of:

FieldWhat
tcpa port that accepts connections on loopback
httpan http:// URL that answers 2xx or 3xx

and timeout_s, the seconds to wait: 60 by default, up to 86,400.

state

Absolute directories or files, not nested in each other and not inside /miroir. Each reset restores them, and empties /tmp, /var/tmp and /dev/shm.

Left out, the state is every path the processes’ users can write. Every process then needs a non-root user.

apps.<name>

App names are lowercase letters, digits, _ and -, starting with a letter or a digit. Each app has an api, an mcp server, a database, or several. At least one app has an api, and at least one has a database.

FieldWhat
descriptionwhat the app is; required when several apps have an api
api.base_urlthe API’s http:// URL on loopback
api.openapithe absolute path of its OpenAPI spec, JSON or YAML, which api_docs serves
api.omitkeys dropped from its JSON answers, at any depth: key, or parent.key for a key of an object under parent; * matches any run of characters, and {a,b} either
mcp.urlthe http:// URL on loopback of its MCP server; one app at most
database.urla postgres://, postgresql:// or mysql:// URL that names a database
database.schemasthe schemas to read; all of them when unset
database.ignoretables, or table.columns, whose changes never count
database.time.excludetable.columns whose times never move
database.time.epochtable.column globs of integer Unix-time columns, each with its unit, s or ms

The database user must be able to create triggers. A key column can’t be ignored, and an epoch pattern must match a 32- or 64-bit integer column.

personas.<name>

FieldWhat
descriptionwho the agent is, as the prompt says
headersheaders by app, pinned on every request to that app’s API or MCP server

Pinned headers win over the agent’s. When a persona pins headers for an app, the agent’s own Cookie header to that app is dropped.

sinks

FieldWhat
smtpthe SMTP sink’s port
httpthe HTTP sink’s port, not the same as smtp
responsescanned answers by /path or METHOD /path, where a trailing * matches a prefix

A canned answer has status (200 by default), json or body (not both), and headers.

quiet

FieldDefaultWhat
commandrequireda command that exits 0 once the apps’ background work is done
timeout_s30how long to wait for two passes in a row, up to 86,400

time

FieldDefaultWhat
anchorbakewhen the seed data is dated: bake, or an RFC 3339 instant
hooknonea command each reset runs to move dates outside the databases
captured{}when each captured world’s snapshot was taken, by world

hook gets MIROIR_SHIFT_DAYS and MIROIR_SHIFT_DATE_DAYS, and can’t go with captured.

Task file

Each *.yaml or *.yml file in /miroir/tasks/ is a task. Probes can also go in /miroir/tasks/probes/<task-id>.yaml, as a list. Unknown fields are errors.

Top level

FieldDefaultWhat
idthe file nameunique among the tasks
splittraintrain, validation or test
worldthe only worldthe world each reset restores; required with several
personathe only personawho the agent acts as; required with several
instructionrequiredwhat the agent is asked to do
answernonethe normal form of the submitted answer: integer, ids or date
max_steps50the tool calls the episode allows
setupnoneSQL run on the only database at each reset, before the apps start
checksrequiredthe checks, at least one
allowed_changesrequired, or any_changethe net changes the task may make
any_changefalseallow every change, in place of allowed_changes
harm_reward0the reward for harm, from -1 to 0
null_max0the most an immediate empty submit may earn, from 0 to 1
goldenrequireda run that must earn 1, ending with submit
probes[]runs whose reward must stay within bounds
coworkers[]colleagues a model plays; see Coworkers
events[]requests sent at clock minutes; see Clock and events

With several worlds, a world’s tasks are all test, or none are.

checks

FieldWhat
nameunique; scope is reserved
sqla query returning one value: a boolean, or a number from 0 to 1
commanda command that scores what it prints on exit 0 (1 if nothing), and 0 otherwise
appthe database sql reads, when several apps have one
dbepisode: run sql on the episode database instead
weightits share of the reward, in (0, 1]; the weights sum to 1
gatetrue: it must score 1, or the episode is harm
bythe clock minute it is scored at, from 1 to 525,600; weighted checks only

A check has exactly one of sql and command, and exactly one of weight and gate. A check runs for up to 10 seconds. A command check gets MIROIR_EPISODE_DB and MIROIR_DATABASE_URL.

allowed_changes

FieldWhat
tablethe table, schema-qualified outside the default schema
opinsert, update, delete, truncate or schema
columnsfor update: the columns it may change; any when unset
appthe app whose database it is, when several apps have one

Steps

golden and each probe’s steps are lists of tool calls:

- {tool: api_request, arguments: {method: GET, path: /deals}}
- {tool: submit, arguments: {answer: "3"}}

tool is one of the agent tools, a tool of the app’s MCP server, or coworker_reply (with a coworker and a text) to stand for a coworker’s answer. The last step, and only the last, is submit.

probes

FieldWhat
nameunique within the task
stepsthe tool calls, ending with submit
max_rewardthe most it may earn
min_rewardthe least it may earn

A probe has at least one of max_reward and min_reward.

coworkers

FieldWhat
name1 to 64 lowercase letters, digits, _ or -
descriptionwho they are
scriptwhat they know, and how they act
headerstheir headers, by app
inbox.sqla query returning a JSON array of messages, each with an id and a text
inbox.appthe database to query, when several apps have one
replythe request that posts an answer: app, method, path and body, with {text} and {field} placeholders

events

FieldWhat
name1 to 64 lowercase letters, digits, _ or -
atthe clock minute it is sent at, from 1 to 525,600
headersthe sender’s headers, by app
requestapp, method, path and body

Agent tools

Every call counts toward the task’s max_steps, and is recorded in the actions table of the episode database. With several apps, api_request and api_docs take a required app, listed with each app’s description.

api_request

Sends an HTTP request to the app’s API as the persona.

ArgumentWhat
methodGET, POST, PUT, PATCH or DELETE
paththe path and query string, starting with /, such as /deals?owner_id=12
bodysent as JSON; with a content-type header, a string is sent as-is, and an object is form-encoded for application/x-www-form-urlencoded
headersextra headers, as an object of strings; at most 100

Returns the status, the content-type, location and link headers, and the body: parsed when it is JSON, without the keys api.omit names, else text, or null when empty. A body over 64 KiB is cut to fit. A JSON array keeps its first items, and truncated says how many of how many; any other body is cut as text, with truncated: true.

The persona’s headers win over the agent’s. Paths can’t leave the API, such as with ... Redirects are not followed, and a request times out after 30 seconds.

api_docs

Looks up the API in its OpenAPI spec. Listed when an app sets api.openapi.

ArgumentWhat
operationan operation ID, or METHOD /path such as GET /deals/1100; leave it out to list every operation

Without operation, returns operations: each operation’s operation ID, method, path and summary. With one, returns its operation ID, summary, description, parameters, request_body and responses. A $ref used once is replaced by what it points at; one used more stays, and schemas shows each such schema once, by its $ref. go-swagger’s x-go-name and x-go-package, which name its generated code, are left out.

run_code

Runs a bash command in the sandbox. Listed on the code surface, in place of api_request, when the env has a sandbox.

ArgumentWhat
commandthe bash command, up to 1 MiB

Returns exit_code and output (stdout and stderr), with timed_out or truncated when the 60-second or 64 KiB limit cut it.

wait

Lets time pass in the apps. Listed for tasks with a clock.

ArgumentWhat
minutesa whole number from 1 to 10,080

Returns waited_minutes and elapsed_minutes. It ends early when an event fires.

submit

Ends the episode, which is then graded.

ArgumentWhat
answerthe answer the task asks for, if any, as a string

Returns submitted: true. When the task has an answer form and the answer doesn’t fit it, the call fails with invalid_args, and the episode goes on.

The app’s MCP tools

On the mcp surface, the app’s MCP server tools replace api_request and api_docs. Miroir passes the arguments through, with the persona’s headers.

Errors

A failed call returns result: null and an error:

error_typeWhen
invalid_argsthe arguments are wrong
tool_not_foundthe tool doesn’t exist in this env or task
execution_errorthe call failed, such as a refused connection
transport_errorthe sandbox could not be reached
timeoutthe call took too long, or the episode’s max_seconds ran out

Episode database

The episode database is a SQLite file, /miroir/episode.db, emptied at each reset. Checks with db: episode query it, and command checks find its path in MIROIR_EPISODE_DB. JSON columns hold text; read them with SQLite’s json_extract.

CREATE TABLE actions (seq INTEGER PRIMARY KEY, tool TEXT NOT NULL, app TEXT, method TEXT,
                      path TEXT, status INTEGER, latency_ms INTEGER NOT NULL,
                      arguments TEXT NOT NULL, result TEXT, via TEXT);
CREATE TABLE effects (seq INTEGER PRIMARY KEY, kind TEXT NOT NULL, data TEXT NOT NULL);
CREATE TABLE changes (app TEXT, tbl TEXT NOT NULL, op TEXT NOT NULL, pk TEXT NOT NULL,
                      before TEXT, after TEXT, columns TEXT);
CREATE TABLE answer (value TEXT);

changes

The episode’s net changes, written before the checks run.

ColumnWhat
appthe app, when several have a database; else NULL
tblthe table, schema-qualified outside the default schema
opinsert, update, delete, truncate or schema
pkthe row’s key columns, as a JSON object; {} for a table without a key
beforethe row before, as a JSON object; NULL for an insert
afterthe row after, as a JSON object; NULL for a delete
columnsfor an update, the columns that changed, as a JSON array

effects

The emails and HTTP calls the sinks caught, in order.

kinddata
emailfrom, to, cc, bcc (lists of addresses), subject, text, html
httpmethod, path, query (an object), headers (without Authorization), body

actions

Every tool call, in order. arguments and result are JSON; result holds the error when the call failed. Calls the agent didn’t make itself have a via:

viatoolWhat
NULLthe toola call of the agent
run_codeapi_requesta request the agent’s code sent
coworkercoworker_replya coworker’s reply
eventeventa clock event

answer

The submitted answer, in its normal form when the task has an answer form.

Examples

-- Only invoice 4001 changed.
SELECT count(*) = 0 FROM changes WHERE tbl = 'invoices' AND json_extract(pk, '$.id') <> 4001;

-- Marcus got exactly one email.
SELECT count(*) = 1 FROM effects
WHERE kind = 'email' AND json_extract(data, '$.to[0]') = 'marcus@acme.test';

-- The payment provider was charged 1,250.00 once.
SELECT count(*) = 1 FROM effects
WHERE kind = 'http' AND json_extract(data, '$.path') = '/stripe/v1/payment_intents'
  AND json_extract(data, '$.body.amount') = 125000;

-- The answer is 3.
SELECT value = '3' FROM answer;

Episode results

Step reply

Each step returns observation, reward and done. Until the episode ends, reward is 0 and done is false. The last step has done: true, the reward (or null when the episode could not be graded) and the metadata below.

Metadata

FieldWhat
task_idthe task
successevery check scored 1, with no harm
harma change out of scope, a failed gate, or a fault
checkseach check’s name and score, with gate, by and error when they apply, then the scope gate
out_of_scopeup to 100 net changes outside allowed_changes: tbl, op, pk, columns and app
out_of_scope_counthow many there are in all
answerthe stored answer, or null
terminationsubmit, max_steps, max_seconds, void or crash
world, task_hash, manifest_hash, miroir_versionwhat the episode ran on
clockfor clock tasks: the minutes elapsed, and the events fired with their minute and status
faultwhy the episode broke the env, which made it harm
crashedthe process that exited, and its exit_code
quiet_timeouttrue when the quiet command never passed before grading
invalidwhy Miroir could not grade the episode, whose reward is null
clock_rolledtrue when the date moved during the episode, as at midnight

A faulted episode, or one that could not be graded, has no checks.

Record

The record frame, or Session.finish()["record"], returns the finished episode in full, within 4 MiB. The adapters save it with traces=.

FieldWhat
episode_id, task_idwhich episode
rewardits reward
null_maxthe task’s null_max
metadataas above
signaturea hash of the end state; null when the episode was not graded
diagnosticscounts: calls, client_errors, server_errors, repeated_calls, docs_calls, code_requests, coworker_replies, events
actionseach call’s tool, method, path, status, latency_ms, arguments and result, with app and via when set
changeseach net change’s tbl, op, pk, before, after and columns
effectseach effect’s kind and data
timingsreset_s (each reset step, and the total), episode_s and grading_s
limit_bytesthe size limit, 4 MiB
truncatedwhat was left out to fit the limit, counted by part

The signature reads the times the episode wrote relative to when it ran, so rollouts that end alike share it on any day.

State

The state frame returns episode_id, step_count, task_id, done, reward and success. reward and success stay null until the episode is done.

CLI

Two programs are called miroir: the Rust binary inside the env image, and the Python CLI on the host.

In the image

CommandDoes
miroir runserves the env; the image’s default command. See Serve an env
miroir bakeseeds every world and keeps its state, at image build. See the manifest
miroir checkchecks that the env and its tasks grade reliably. See Check the env
miroir sandboxserves the sandbox that runs the agent’s code, in a container of its own
miroir importscrubs production dumps and traces into seed data. See Import
miroir export harborwrites each task as a Harbor task. See Run in Harbor

check takes --json, --mutate and --world W.

import takes --dump APP=FILE (one per app), --scrub FILE, --key FILE, --out DIR and, optionally, --traces FILE.

export harbor takes --image IMAGE, the env image as Harbor’s Docker finds it, and --out DIR, empty or missing.

miroir --version prints the version. Every command must run as the container’s entrypoint, or as a child of its init.

On the host

Install with uv pip install miroir.

CommandDoes
miroir pool --size N --urls FILE -- COMMAND...keeps N containers healthy, listed in FILE. See Pools
miroir review TRACES... --tasks DIRlabels end states; wrong grades become probes. See Review grades
miroir calibrate TRACES... --model M --out FILEclasses tasks as solved, learnable or out of reach. See Calibrate tasks
miroir draft TRACES --world W --tasks DIRwrites a draft task for each scrubbed trace. See Tasks from traces
miroir derive URL TRACES --world W --tasks DIRreplays the drafts and writes their checks
OptionOfWhat
--jsonreviewprint the queue as JSON, and ask nothing
--label TASK@SIGNATURE=LABELreviewlabel without asking: correct, should_fail or should_pass
-k Kcalibratek for pass@k and pass^k; by default the most rollouts of a task
--split Sdraftthe drafts’ split; train by default
--token-var VARderivethe variable that holds the env’s MIROIR_TOKEN

TRACES are the record files the adapters save, or directories of them. For draft and derive, it is the traces.jsonl that miroir import writes.

Environment variables

You set

VariableRead byWhat
MIROIR_TOKENrunthe bearer token every route but /health requires; unset, anyone can act
MIROIR_AGENT_TOKENruna second bearer token, which opens /mcp alone, for an agent that calls it itself; needs MIROIR_TOKEN, and must differ from it
MIROIR_PORTrun, sandboxthe port to serve on; 8000 by default
MIROIR_SANDBOXrun, checkhttp://HOST:PORT of a sandbox, which enables run_code
MIROIR_LOG_BUDGET_MBrun, checkthe change-log size past which an episode faults, shared by the databases; 1024 by default
MIROIR_ENV_VERSIONrunthe version /metadata reports, such as the product image’s tag
SANDBOX_IMAGEsandbox/check.sh, python/tests/docker.shthe sandbox image to start

Miroir sets

VariableForWhat
MIROIR_WORLDbake and seed commandsthe world being baked
MIROIR_SHIFT_DAYStime.hookwhole days the timestamps move
MIROIR_SHIFT_DATE_DAYStime.hookcalendar days the dates move
MIROIR_EPISODE_DBcommand checksthe path of the episode database
MIROIR_DATABASE_URLcommand checksthe URL of the check’s app database, or the only one
API_<APP>the agent’s code in the sandboxeach app’s API, valid during one run_code call
MIROIR_POOLthe miroir pool commandthe pool’s name, to label what it starts

Every process and command also gets the manifest’s env, and a process its own env. None of them sees MIROIR_TOKEN or MIROIR_AGENT_TOKEN.

Develop Miroir

Layout

PathWhat
src/the miroir binary
python/the client, the TRL and verifiers adapters, the host-side CLI
sandbox/the image that runs run_code commands
fixtures/example products and their envs
examples/real products made envs: Gitea
tests/Docker integration tests, and OpenEnv conformance
tools/reset timing and pool soak benchmarks
docs/this book
skills/the Agent Skill for coding agents

Checks

cargo fmt --check && cargo clippy --all-targets --locked -- -D warnings
cargo test --locked                                    # unit tests
cargo test --locked --test integration -- --ignored    # builds the fixture images; needs Docker
(cd python && uv run ruff check . && uv run ty check && uv run pytest -q)   # -m integration: Docker
(cd tests/openenv && uv run pytest -q)                 # OpenEnv conformance, on acme-crm-env

docker buildx bake builds the binary’s image, the sandbox and every fixture env.

The docs

The docs are an mdBook in docs/:

mdbook serve docs    # http://localhost:3000, rebuilt on save
mdbook build docs    # into docs/book

The skill

skills/miroir restates this book for coding agents, as an Agent Skill: SKILL.md holds the workflows, and references/ the fields and the check stages. When a change touches the manifest, the task format, the tools or check, update the skill too. .claude-plugin/marketplace.json lists it for Claude Code.

uvx --from skills-ref==0.1.1 agentskills validate skills/miroir
claude plugin validate --strict .