RuntimeConfig — One Contract to Describe an Entire Run

Running a simulation involves a lot of decisions — which environment, how many robots of which type, which scenario, which sensors to enable, which options to switch on. RuntimeConfig bundles all of that into a single declarative object. Think of it as the run's purchase order.

What vs. How

The central design principle of RuntimeConfig is separating "what to run" (declaration) from "how to run it" (engine).

Rendering diagram…

The user or API specifies only "what." The "how" — which GPU node, which process, physics step size — is handled by the orchestrator, worker, and runner. This separation means the same purchase order produces the same run on any node.

Key fields covered by RuntimeConfig:

Options Default to OFF — No Wasted GPU Time

There is one firm principle in option design.

💡 Heavy options default OFF — mission overlay, video export, and other heavyweight features should only activate when explicitly requested. Leaving them on by default burns GPU and time on every validation run that doesn't need them. "Lightweight by default, explicit when needed" is the philosophy behind the contract's default values.

⚠️ Test only through this contract — launching the runner directly over SSH bypasses the RuntimeConfig path and validates behavior that differs from the actual production path. Validation is only meaningful when it goes through this contract (POST /runs) on the same path as production.

Why a Single Contract

If the description of a run is scattered across multiple places — half in the API, half in environment variables, half in code defaults — reproducibility breaks down. With a single entry point like RuntimeConfig, anyone who has "this purchase order" can reproduce the same run identically. This is the self-containment philosophy applied to run execution.

In a nutshell

📌 RuntimeConfig is the single contract that describes a run — bundling environment, robots, scenario, sensors, and options into one object. It separates "what to run" from "how to run it," keeps heavy options off by default, and requires validation to go through this contract (the production path).