Skip to main content
The manifest is /miroir/miroir.yaml in the world image. For a worked example, see Write the manifest. It is YAML, read strictly:
  • An unknown key is an error. Every error names the field path and the fix, such as processes[2].cwd: 'app' must be an absolute path, such as /app.
  • Commands are lists, [program, arg, ...], run without a shell. Write [sh, -c, "..."] when you need one.

Top-level keys

Processes

Each entry of processes is a long-running process. At least one must have datastore: true, and every datastore comes before the other processes.

Database

Dates

A world is seeded once, at build time, but tasks talk about “overdue” invoices or deals “stale for 30 days”. To keep those true, every boot moves the database’s dates from the bake to the day of the trial: These values stay where they are:
  • columns listed in database.time.exclude;
  • generated columns;
  • values on or after 9000-01-01, such as 9999-12-31 for “never”;
  • Unix times of 0 or less.
The shift runs with triggers disabled, so a product trigger that stamps updated_at does not fire. Whole days and calendar days differ for part of each day. An image baked at 23:00 UTC and booted at 01:00 the next day moves dates by 1 and timestamps by 0. That is why a check never compares a date column with a timestamp column (authoring rules). If a constraint refuses a moved value, the boot fails and names the table. List the column in database.time.exclude.

Restored data

database.time.captured is for data restored from a dump. The bake moves the restored rows from that time to the bake’s start, so a dump taken weeks before the build keeps its relative ages. The seed’s writes come after and are not moved. A captured time later than the bake’s start is refused.

Sinks

The product cannot reach the internet: its compose network is internal: true. Instead, point its outgoing mail and HTTP at the sinks, recorders that listen on loopback. What they record becomes the sent_emails and sent_requests tables of the evidence.
  • SMTP records each email: the sender, the to and cc recipients, the envelope recipients missing from the headers (as bcc), the subject, the text and the HTML. Point the product’s SMTP settings at 127.0.0.1:<port>; the fixture sets SMTP_URL=smtp://127.0.0.1:2525.
  • HTTP records each request: method, path, query parameters, headers (names lower-case, authorization dropped) and body (JSON as JSON, other text as a JSON string, an empty body as null). Point base URLs at http://127.0.0.1:<port>. The fixture sets STRIPE_API_BASE=http://127.0.0.1:9000/stripe, and Gitea allows webhooks to 127.0.0.1:9000.
  • Responses are keyed "[METHOD ]/path[*]", each {status, json | body, headers}. An exact path beats a prefix (a key ending in *), a longer prefix beats a shorter one, and a key with a method beats one without. Unmatched requests get 200 with an empty body.
An email over 25 MiB is recorded truncated, and a request body over 25 MiB is refused; both add a sink fault. The sinks answer during the bake but record only from the boot, and the boot clears what start-up sent.

Quiet

Products do work in the background: a queued email, a webhook delivery, a search index. quiet is a command that exits 0 when that work is done, so the evidence holds everything the agent’s requests set off. Miroir waits until quiet passes twice in a row, within 30 s, at bake, at boot and at collect. At bake and boot a timeout fails; at collect it is recorded as a quiet_timeout fault. The fixture checks two Redis queue lengths; Gitea runs gitea manager flush-queues.
  • Turn schedulers and cron off in env (SCHEDULER_ENABLED: "false"), so nothing changes while the world idles: a run where the agent does nothing must change nothing.
  • Don’t leave a background process holding the command’s output open. Miroir reads the command’s stderr to explain a failure, so such a run waits out the full 30 s.