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

Serve an env

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

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

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

Routes

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

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

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

Settings

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

Security

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

Recovery

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

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

Stop

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