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
| Program | Runs | Does |
|---|---|---|
miroir (Rust) | inside the env image | bakes, resets, serves episodes, grades, checks, scrubs dumps |
miroir (Python) | on the host | client, 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_urlis where the agent’s requests go.api.openapiis the specapi_docsserves.api.omitlists 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.keymatches only in an object held underparent, sohead.repodrops a pull request’s copy of its repository and keeps an activity’srepo. Braces give alternatives:{user,assignee}.createddrops when a user’s account was made, and keeps when a commit was.database.urlis 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.ignorelists tables, ortable.columns, whose changes never count, such as alast_used_atthe 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:
- Start the datastores and wait until each database answers.
- Run the
bakecommands. - Start the apps and wait for quiet.
- Run the
seedcommands and wait for quiet. - Install the triggers that log row changes.
- 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
- Kill every process.
- Restore the state, copying only the files that changed, and empty
/tmp,/var/tmpand/dev/shm. - Start the datastores and move every date forward by the days since bake. See Dates.
- Run the task’s
setupSQL, if any. - Start the apps and wait for quiet.
- 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:
| Kind | Runs | Scores |
|---|---|---|
sql | on the app’s database, read-only | the query’s single value |
sql with db: episode | on the episode database (SQLite) | the query’s single value |
command | in the env, as a command | what 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:
| Form | Accepts | Stored as |
|---|---|---|
integer | a whole number | 42 |
ids | ids separated by commas or spaces | sorted, deduplicated, 12,15,18 |
date | YYYY-MM-DD | the 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;
checktests for that.
Grading
When an episode ends
| Ending | When |
|---|---|
submit | the agent calls submit |
max_steps | the agent has made max_steps tool calls |
max_seconds | a call comes after the reset’s max_seconds ran out |
crash | a process of the product exited |
void | Miroir lost part of the record during a wait |
The episode’s metadata gives the ending as termination.
What grading does
- Wait for quiet, so background work has landed.
- 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
schemachange. - Store the net changes in the episode database.
- Run the checks. App database checks read the same snapshot as the net changes.
- Compare the net changes with
allowed_changes. This is thescopegate.
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
crashednames 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
| Stage | Passes when |
|---|---|
static | the manifest and every task load and validate |
users | every process has a user (write user: root to keep one as root) |
idle | resets 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 |
mcp | the app’s MCP server lists its tools (only with an MCP server) |
sandbox | the sandbox reaches nothing of the env’s but its proxy (only with MIROIR_SANDBOX) |
Task stages
| Stage | Passes when |
|---|---|
golden | the golden run succeeds, and every call works: HTTP below 400, code exits 0, no tool error |
null | an immediate empty submit earns at most null_max (0 by default), and every gate holds |
repeat | two more golden runs earn the same reward and the same check scores |
reset | the 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 |
writes | no file changed outside the state directories |
probes | each probe’s reward stays within its bounds |
hedge | submitting the golden answer among wrong guesses earns at most null_max |
drift | the 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
| Option | Does |
|---|---|
--json | print the full report as JSON |
--world W | check only the tasks of world W |
--mutate | also 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 have | app is required in |
|---|---|
| an API | api_request and api_docs calls, golden and probe steps, event and reply requests |
| a database | sql 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
setupruns 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-01on, such as a9999-12-31that 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
waitstep in a golden run or probe takes exactlyminutes. - Clock minutes go up to 525,600, a year.
- A task with a clock can’t take a
dateanswer, and can’t run in an env withtime.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
| Field | What |
|---|---|
name | 1 to 64 lowercase letters, digits, _ or - |
description | who they are |
script | what they know, and how they act |
headers | their own headers, by app, which their replies send |
inbox.sql | a query on the app’s database that returns a JSON array of messages, each with an id and a text |
inbox.app | the database to query, when several apps have one |
reply | the 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
- Messages already in the inbox at reset are never answered.
- The client asks for turns with a
coworkersframe. 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 theirdescriptionandscript, then the last 20 messages. - The client sends that chat to a model and returns the answer in a
coworker_replyframe. Miroir posts it throughreply, 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)), anddataset(..., coworkers=True). - verifiers:
--env.taskset.coworker_model,--env.taskset.coworker_base_urland--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
| Limit | Value |
|---|---|
| one call | 60 s |
| output returned | 64 KiB |
| command | 1 MiB |
| a request or answer body | 8 MiB |
| all requests of an episode’s code | 64 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
| Route | What |
|---|---|
GET /health | {"status": "healthy", "leased": false}, or 503 while the env can’t serve |
GET /ws | the OpenEnv session; see Protocol |
POST /mcp | MCP over JSON-RPC; see Protocol |
POST /episode, POST /episode/end | start and end an episode without a WebSocket; see Protocol |
GET /metadata | name, description, version, miroir_version, manifest_hash, tasks_hash |
GET /schema | JSON schemas of the frames |
GET /openapi.json | these routes |
GET /list_environments | the env’s name, in a list |
GET /{name}/splits | the splits that have tasks |
POST /{name}/tasks | a split’s tasks: {"split": "train"} |
POST /{name}/num_tasks | how many tasks a split has: {"split": "train"} |
POST /{name}/task | one task: {"split": "train", "index": 0} |
POST /{name}/task_range | a 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 asAuthorization: Bearer <token>;/mcpalso takes?token=. The product’s processes don’t see it. - When an agent calls
/mcpitself, as over HTTP episodes, give itMIROIR_AGENT_TOKENinstead: a second token that opens/mcpalone, so the agent can’t end its episode, start another or read the task listings. It needsMIROIR_TOKENset, and must differ from it. - Requests that carry an
Originheader, 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"}}
| Frame | data | Reply |
|---|---|---|
reset | which task, and options (below) | observation: the task the agent starts on |
step | an action (below) | observation: the tool list or the call’s result |
state | none | state: episode_id, step_count, task_id, done, reward, success |
record | episode_id, optional | record: the finished episode’s record |
coworkers | {} | coworkers: the turns coworkers owe |
coworker_reply | coworker, text | coworker_reply: the app’s HTTP status |
close | none | the 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
| Field | What |
|---|---|
task_id | the task to run; wins over the others |
split | the split to draw from; train by default |
index | the split’s task at this index, in id order |
seed | the split’s task at seed mod the number of tasks |
episode_id | an id for the episode, 1 to 255 characters; a UUID by default |
max_seconds | after this many seconds, the next call ends the episode as it stands |
coworkers | true 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:
| Parameter | What |
|---|---|
surface | api (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_id | the episode the calls are for |
token | the 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'
| Route | Body | Answer |
|---|---|---|
POST /episode | a reset frame’s data; empty draws a task | the reset’s observation, reward and done, and the episode_id |
POST /episode/end | none | the 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 startprintsID URLas its last line, such as3f2a… http://127.0.0.1:49153.COMMAND stop IDremoves 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
/healthevery 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 runneeds a PID namespace of its own: the script starts it withunshare --pid --fork --mount-proc tini -- miroir run. /runis 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
| Service | Runs | Holds |
|---|---|---|
main | the agent, as the user agent; then the verifier | the agent token, in the agent’s MCP settings |
app | the env image, on a network with no way out | both tokens |
start | POST /episode for the task, before main starts | the 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
publicnetwork mode: the agent’s container joins the env’s network, which theno-networkandallowlistmodes take away or bypass. - The tasks are Docker Compose tasks: they run on Harbor’s
dockerenvironment 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
| Call | Does |
|---|---|
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
| Function | Returns |
|---|---|
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)
| Option | What |
|---|---|
urls or urls_file | the containers: a list, or a file miroir pool writes |
token | the env’s MIROIR_TOKEN |
traces | a directory to save each episode’s record in, for review and calibration |
harm_reward | caps the reward of a harmful episode, from -1 to 0 |
max_seconds | a time limit per episode, 1 to 86,400 |
surface | api, or code for run_code in place of api_request |
coworker | a 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.:
| Option | What |
|---|---|
urls or urls_file | the containers: a JSON list of base URLs, or a file miroir pool writes |
split | the split to run; train by default |
token_var | the variable that holds the env’s MIROIR_TOKEN |
token | the token itself, for a run that passes no variables to the env |
traces | a directory to save each episode’s record in |
calibration, keep | a calibration file, and the classes to run; ["learnable"] by default |
harm_reward | caps the reward of a harmful episode, from -1 to 0 |
surface | api (default), mcp for the app’s MCP tools, or code for run_code |
max_seconds | a time limit per episode, 1 to 86,400 |
coworker_model | the model that plays coworkers |
coworker_base_url | its OpenAI-compatible endpoint |
coworker_api_key_var | the 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?
| Label | Means | Writes |
|---|---|---|
correct | the grade is right | the label |
should_fail | it earned too much | the label, and a probe with max_reward set to the task’s null_max |
should_pass | it earned too little | the 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
| Option | Does |
|---|---|
--label TASK@SIGNATURE=LABEL | label an end state without asking; repeat for more |
--json | print 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
| Class | When |
|---|---|
learnable | the rewards vary |
solved | every rollout succeeds |
out_of_reach | every 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
| Option | What |
|---|---|
--dump APP=FILE | a plain SQL dump of an app’s database; one per app |
--scrub FILE | the scrub spec |
--key FILE | the key, at least 32 bytes |
--traces FILE | production agent traces to scrub too; see Tasks from traces |
--out DIR | where 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}
| Kind | Becomes |
|---|---|
name | each word replaced by a fake word, keeping its case |
email | a fake address, such as 3f9a1c2e4b7d8a90@1c2e4b7d.example |
phone | fake digits in the same format |
secret | a fake secret |
text | free text with its emails, and the known names, phones and secrets, replaced |
blank | NULL |
keep | unchanged |
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
| File | What |
|---|---|
<app>.sql | the scrubbed dump of each app |
traces.jsonl | the scrubbed traces, with --traces |
report.json | rows 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:
miroir import --tracesscrubs them, along with the dumps.miroir draftwrites a draft task for each trace.miroir derivereplays 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."}
| Field | What |
|---|---|
id | the trace’s id: lowercase letters, digits, _ and - |
consent | the basis on which the trace may be used; traces without one are left out |
request | what the user asked |
calls | the api_request and api_docs calls, each with its arguments and, optionally, the status it got |
answer | the agent’s answer, if any |
persona | the 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:
- Replays the calls, and keeps those that work on the snapshot.
- Replays the kept calls again, from a fresh reset.
- Writes checks for what both replays agree on, a gate against any other change or effect,
and the
allowed_changesthat 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
| Field | Default | What |
|---|---|---|
miroir | required | format version; must be 1 |
name | required | letters, digits, ., _ and -; the env’s name in routes |
description | required | what the product is; /metadata shows it |
processes | required | what 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 |
state | derived | the directories each reset restores |
apps | required | the apps, by name |
personas | required | the users the agent can act as, by name |
sinks | none | the sinks |
quiet | none | the command that tells when background work is done |
time | anchor: bake | how the data’s dates follow the clock |
system_prompt | none | a 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[]
| Field | Default | What |
|---|---|---|
name | required | unique |
command | required | the command to run |
user | root | the user it runs as; root fails check unless written user: root |
cwd | none | an absolute working directory |
env | {} | variables for this process |
datastore | false | started first, and alone while a reset restores and moves the data |
ready | none | how Miroir tells it is ready |
Datastores come before every other process, and there is at least one.
ready takes exactly one of:
| Field | What |
|---|---|
tcp | a port that accepts connections on loopback |
http | an 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.
| Field | What |
|---|---|
description | what the app is; required when several apps have an api |
api.base_url | the API’s http:// URL on loopback |
api.openapi | the absolute path of its OpenAPI spec, JSON or YAML, which api_docs serves |
api.omit | keys 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.url | the http:// URL on loopback of its MCP server; one app at most |
database.url | a postgres://, postgresql:// or mysql:// URL that names a database |
database.schemas | the schemas to read; all of them when unset |
database.ignore | tables, or table.columns, whose changes never count |
database.time.exclude | table.columns whose times never move |
database.time.epoch | table.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>
| Field | What |
|---|---|
description | who the agent is, as the prompt says |
headers | headers 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
| Field | What |
|---|---|
smtp | the SMTP sink’s port |
http | the HTTP sink’s port, not the same as smtp |
responses | canned 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
| Field | Default | What |
|---|---|---|
command | required | a command that exits 0 once the apps’ background work is done |
timeout_s | 30 | how long to wait for two passes in a row, up to 86,400 |
time
| Field | Default | What |
|---|---|---|
anchor | bake | when the seed data is dated: bake, or an RFC 3339 instant |
hook | none | a 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
| Field | Default | What |
|---|---|---|
id | the file name | unique among the tasks |
split | train | train, validation or test |
world | the only world | the world each reset restores; required with several |
persona | the only persona | who the agent acts as; required with several |
instruction | required | what the agent is asked to do |
answer | none | the normal form of the submitted answer: integer, ids or date |
max_steps | 50 | the tool calls the episode allows |
setup | none | SQL run on the only database at each reset, before the apps start |
checks | required | the checks, at least one |
allowed_changes | required, or any_change | the net changes the task may make |
any_change | false | allow every change, in place of allowed_changes |
harm_reward | 0 | the reward for harm, from -1 to 0 |
null_max | 0 | the most an immediate empty submit may earn, from 0 to 1 |
golden | required | a 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
| Field | What |
|---|---|
name | unique; scope is reserved |
sql | a query returning one value: a boolean, or a number from 0 to 1 |
command | a command that scores what it prints on exit 0 (1 if nothing), and 0 otherwise |
app | the database sql reads, when several apps have one |
db | episode: run sql on the episode database instead |
weight | its share of the reward, in (0, 1]; the weights sum to 1 |
gate | true: it must score 1, or the episode is harm |
by | the 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
| Field | What |
|---|---|
table | the table, schema-qualified outside the default schema |
op | insert, update, delete, truncate or schema |
columns | for update: the columns it may change; any when unset |
app | the 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
| Field | What |
|---|---|
name | unique within the task |
steps | the tool calls, ending with submit |
max_reward | the most it may earn |
min_reward | the least it may earn |
A probe has at least one of max_reward and min_reward.
coworkers
| Field | What |
|---|---|
name | 1 to 64 lowercase letters, digits, _ or - |
description | who they are |
script | what they know, and how they act |
headers | their headers, by app |
inbox.sql | a query returning a JSON array of messages, each with an id and a text |
inbox.app | the database to query, when several apps have one |
reply | the request that posts an answer: app, method, path and body, with {text} and {field} placeholders |
events
| Field | What |
|---|---|
name | 1 to 64 lowercase letters, digits, _ or - |
at | the clock minute it is sent at, from 1 to 525,600 |
headers | the sender’s headers, by app |
request | app, 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.
| Argument | What |
|---|---|
method | GET, POST, PUT, PATCH or DELETE |
path | the path and query string, starting with /, such as /deals?owner_id=12 |
body | sent 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 |
headers | extra 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.
| Argument | What |
|---|---|
operation | an 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.
| Argument | What |
|---|---|
command | the 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.
| Argument | What |
|---|---|
minutes | a 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.
| Argument | What |
|---|---|
answer | the 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_type | When |
|---|---|
invalid_args | the arguments are wrong |
tool_not_found | the tool doesn’t exist in this env or task |
execution_error | the call failed, such as a refused connection |
transport_error | the sandbox could not be reached |
timeout | the 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.
| Column | What |
|---|---|
app | the app, when several have a database; else NULL |
tbl | the table, schema-qualified outside the default schema |
op | insert, update, delete, truncate or schema |
pk | the row’s key columns, as a JSON object; {} for a table without a key |
before | the row before, as a JSON object; NULL for an insert |
after | the row after, as a JSON object; NULL for a delete |
columns | for an update, the columns that changed, as a JSON array |
effects
The emails and HTTP calls the sinks caught, in order.
kind | data |
|---|---|
email | from, to, cc, bcc (lists of addresses), subject, text, html |
http | method, 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:
via | tool | What |
|---|---|---|
| NULL | the tool | a call of the agent |
run_code | api_request | a request the agent’s code sent |
coworker | coworker_reply | a coworker’s reply |
event | event | a 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
| Field | What |
|---|---|
task_id | the task |
success | every check scored 1, with no harm |
harm | a change out of scope, a failed gate, or a fault |
checks | each check’s name and score, with gate, by and error when they apply, then the scope gate |
out_of_scope | up to 100 net changes outside allowed_changes: tbl, op, pk, columns and app |
out_of_scope_count | how many there are in all |
answer | the stored answer, or null |
termination | submit, max_steps, max_seconds, void or crash |
world, task_hash, manifest_hash, miroir_version | what the episode ran on |
clock | for clock tasks: the minutes elapsed, and the events fired with their minute and status |
fault | why the episode broke the env, which made it harm |
crashed | the process that exited, and its exit_code |
quiet_timeout | true when the quiet command never passed before grading |
invalid | why Miroir could not grade the episode, whose reward is null |
clock_rolled | true 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=.
| Field | What |
|---|---|
episode_id, task_id | which episode |
reward | its reward |
null_max | the task’s null_max |
metadata | as above |
signature | a hash of the end state; null when the episode was not graded |
diagnostics | counts: calls, client_errors, server_errors, repeated_calls, docs_calls, code_requests, coworker_replies, events |
actions | each call’s tool, method, path, status, latency_ms, arguments and result, with app and via when set |
changes | each net change’s tbl, op, pk, before, after and columns |
effects | each effect’s kind and data |
timings | reset_s (each reset step, and the total), episode_s and grading_s |
limit_bytes | the size limit, 4 MiB |
truncated | what 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
| Command | Does |
|---|---|
miroir run | serves the env; the image’s default command. See Serve an env |
miroir bake | seeds every world and keeps its state, at image build. See the manifest |
miroir check | checks that the env and its tasks grade reliably. See Check the env |
miroir sandbox | serves the sandbox that runs the agent’s code, in a container of its own |
miroir import | scrubs production dumps and traces into seed data. See Import |
miroir export harbor | writes 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.
| Command | Does |
|---|---|
miroir pool --size N --urls FILE -- COMMAND... | keeps N containers healthy, listed in FILE. See Pools |
miroir review TRACES... --tasks DIR | labels end states; wrong grades become probes. See Review grades |
miroir calibrate TRACES... --model M --out FILE | classes tasks as solved, learnable or out of reach. See Calibrate tasks |
miroir draft TRACES --world W --tasks DIR | writes a draft task for each scrubbed trace. See Tasks from traces |
miroir derive URL TRACES --world W --tasks DIR | replays the drafts and writes their checks |
| Option | Of | What |
|---|---|---|
--json | review | print the queue as JSON, and ask nothing |
--label TASK@SIGNATURE=LABEL | review | label without asking: correct, should_fail or should_pass |
-k K | calibrate | k for pass@k and pass^k; by default the most rollouts of a task |
--split S | draft | the drafts’ split; train by default |
--token-var VAR | derive | the 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
| Variable | Read by | What |
|---|---|---|
MIROIR_TOKEN | run | the bearer token every route but /health requires; unset, anyone can act |
MIROIR_AGENT_TOKEN | run | a second bearer token, which opens /mcp alone, for an agent that calls it itself; needs MIROIR_TOKEN, and must differ from it |
MIROIR_PORT | run, sandbox | the port to serve on; 8000 by default |
MIROIR_SANDBOX | run, check | http://HOST:PORT of a sandbox, which enables run_code |
MIROIR_LOG_BUDGET_MB | run, check | the change-log size past which an episode faults, shared by the databases; 1024 by default |
MIROIR_ENV_VERSION | run | the version /metadata reports, such as the product image’s tag |
SANDBOX_IMAGE | sandbox/check.sh, python/tests/docker.sh | the sandbox image to start |
Miroir sets
| Variable | For | What |
|---|---|---|
MIROIR_WORLD | bake and seed commands | the world being baked |
MIROIR_SHIFT_DAYS | time.hook | whole days the timestamps move |
MIROIR_SHIFT_DATE_DAYS | time.hook | calendar days the dates move |
MIROIR_EPISODE_DB | command checks | the path of the episode database |
MIROIR_DATABASE_URL | command checks | the URL of the check’s app database, or the only one |
API_<APP> | the agent’s code in the sandbox | each app’s API, valid during one run_code call |
MIROIR_POOL | the miroir pool command | the 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
| Path | What |
|---|---|
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 .