Skip to main content
A world goes through three stages. miroir bake runs once, when the image is built. miroir run boots the world at the start of every trial. miroir collect writes the evidence after the agent stops. Failure messages name the step that failed, such as boot step 5, so you can look it up below.

Bake

RUN miroir bake, the last RUN of the world image’s Dockerfile, at docker build:
  1. Load the manifest. An image that is already baked (/miroir/bake.json exists) is refused.
  2. Start the sinks. They answer but record nothing, so mail and webhooks sent while seeding succeed.
  3. Start the datastores in order, each until its ready probe passes, then wait until database.url answers.
  4. Run each bake command, with the build’s environment under the manifest env, so Docker ARGs reach it.
  5. With database.time.captured set, move the restored data from that time to the bake’s start.
  6. Start the other processes in order until ready, then wait for quiet.
  7. Run each seed command, then wait for quiet. A process that exited fails the bake.
  8. Install change capture on every table not ignored: a miroir schema holding the change log, and on each table a row trigger, miroir_capture, and a statement trigger, miroir_truncate. The bake refuses:
    • a database.url role that is not a superuser;
    • captured names the grader’s SQLite copy cannot hold, in any ASCII case: two tables, or two columns of one table, with the same name; a table whose evidence name starts with sqlite_; and a column named _op or _change, which the grader adds.
  9. Stop every process in reverse order: SIGTERM, then SIGKILL after 30 s.
  10. Refuse a bake that ran past midnight UTC, since each boot moves dates from the bake’s day.
  11. Write /miroir/bake.json, create the empty /miroir/evidence/, and make /miroir private to root (mode 0700).
A failure prints bake step N, <what>: <why and the fix> and exits 1, which fails docker build.

Boot

miroir run, the world container’s command, once per trial:
  1. Read /miroir/bake.json.
  2. Create /miroir/run/. If it is already there, the container booted before: its dates may have moved already and its database holds that run’s changes. The boot fails and leaves that run’s files as they are. A world boots once per container.
  3. Start the sinks, recording to /miroir/run/effects.jsonl (and faults to faults.jsonl).
  4. Start the datastores until ready, then wait until the database answers.
  5. Shift dates from the bake to today (Dates).
  6. Start the other processes until ready, then wait for quiet.
  7. Clear the change log and the journals, since start-up writes and mail are not the agent’s, and record the tables at the start of the episode in /miroir/run/catalog.json. A process that exited fails the boot.
  8. Audit the listeners (The listener rule).
  9. Write /miroir/run/ready, which the compose healthcheck tests, and log the step timings: booted in 0.8 s: datastores 0.2, shift 0.0, apps 0.4, quiet 0.2 for the fixture.
  10. Supervise. A process that exits is recorded as a crash fault, and the world keeps serving. Every child gets oom_score_adj 1000, so under memory pressure the kernel kills a product process (a recorded crash) before miroir itself.
  11. On SIGTERM, stop the processes in reverse order and exit 0.
A failure in steps 1 to 8 prints boot step N, <what>: <why and the fix> and exits 1. The container stops, main never starts, and Harbor records an environment error before any agent runs.

Collect

miroir collect, run by the task’s collect hook after main has stopped. Harbor runs docker compose exec <service> sh -c 'miroir collect' as root with an almost empty environment, so collect applies the manifest env itself.
  1. Fail if /miroir/run/ready is missing: the world never finished booting.
  2. Wait for quiet. A timeout is recorded as a quiet_timeout fault.
  3. Read the change log and the live table list in one consistent read. Either of these leaves the evidence with no changes:
    • a database that does not answer, recorded as a database fault;
    • a change log over 64 MiB, counting each row’s text plus 1 KiB, recorded as a log_budget fault.
  4. Fold the log into net changes: one per changed row, with the row as the episode found it and as it left it. A table created, dropped or reshaped since boot, or one whose capture trigger is gone, is a schema change; a re-created table is a truncate.
  5. Read the effects and faults journals. An effects journal over 16 MiB is left unread, and recorded as an evidence_budget fault giving its size.
  6. Write /miroir/evidence/evidence.db through a temporary file and a rename. Evidence over 16 MiB is written again with no changes and no effects, plus an evidence_budget fault.
  7. Print a summary, such as evidence: 1 changes, 1 effects, 36864 bytes; faults: [], and exit 0.
Collect exits 1 only for Miroir’s own failures: the world never booted, the fold failed, or no file could be written. The grader then finds no evidence, and the trial voids. Faults never fail collect: they are harm, measured.

The listener rule

At boot, once every process is ready, Miroir reads every TCP listener in the world’s network namespace (/proc/net/tcp and /proc/net/tcp6). Two things fail the boot:
  • a listener off loopback (not 127.0.0.0/8 or ::1) on a port outside expose: port 5432 (db) listens on 0.0.0.0: bind it to 127.0.0.1, or list it in expose;
  • an expose port with no listener off loopback: expose lists 3000 (web), but nothing listens on it off loopback: check the product's bind address.
The name in parentheses is the process whose ready probe uses the port. Bind datastores (which use trust authentication) and everything else to 127.0.0.1, and the product’s API to 0.0.0.0 on its exposed port. A runtime that runs each compose service as a VM also lists the VM’s own daemons there, so such runtimes fail this audit and are not supported.

Security model

The agent is untrusted, and runs as root in main.
  • The product cannot reach the internet. main sits on Harbor’s default network (for its model API) and on world. The world service sits only on world, which is internal: true, so its mail and webhooks land in the sinks.
  • Over TCP, main reaches only the expose ports. Datastores, sinks and every other TCP listener are on loopback, and the boot’s audit refuses a world that breaks this.
  • Capture happens below the API, in triggers the superuser owns. The agent never shares a container with the datastores, the change log or the journals, and a root process writes the evidence after Harbor has stopped main. The product’s roles cannot read /miroir (mode 0700), and a disabled capture trigger shows as a schema change, which is harm.
  • The spec never reaches main. It lives in [verifier.env], which only the verifier receives, and main holds no grader, tests or Miroir binary.
  • Grader inputs are bounded. Only the first 64 KiB of a regular answer file are read, and every SQL statement of the spec runs under a fixed budget of SQLite steps, not a clock. So an agent cannot turn a scored trial into a void, and grading never depends on machine load. The grader runs in its own container.
  • The task’s credential is test data, valid only inside one trial’s private network, and written in instruction.md so that every harness sees it.
  • Identity is not a security boundary. The agent may use any credential it finds, and scope measures every change, whoever made it. What the product can reach through its own features (SSRF) is limited by its own configuration, such as Gitea’s ALLOWED_HOST_LIST.

Failure messages