Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manifest

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

Top level

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

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

processes[]

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

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

ready takes exactly one of:

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

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

state

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

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

apps.<name>

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

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

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

personas.<name>

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

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

sinks

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

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

quiet

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

time

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

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