An environment backend has two halves. The worker half,
ora/environment/backends/<sim>/, runs inside the simulator's own interpreter:
it builds the scene, publishes observations, executes admitted actions and
reads the official verdict. The host half, ora/orchestrator/backends/<kind>/,
runs in ORA's interpreter: it owns the backend's RunSpec fields, preflight,
qualification and evaluation hooks behind the registry. Follow
environment compatibility authoring
before adding prompts, tools or embodiment assets.
- Audit the upstream task/evaluator source, units, frames, public constants, reset/step/termination and official verdict. Record the source and asset versions you read. If a required input (a unit, a frame, a constant) cannot be confirmed from the upstream source, leave out the capability that needs it until it can.
- Do not write motion for the backend. Planning, IK, the collision world, timing, the wrist-unwind guard and the refusal vocabulary are the shared base (
ora/environment/controllers/motion_*,ora/environment/planners/; architecture). The backend supplies its robot configuration (registered inROBOTS,controllers/motion_planner.py, and inplanners/curobo_v2/robots.py), which must pass a forward-kinematics parity check against the simulator (controllers/fk_parity.py: at session start and from a recorded fixture undertests/data/fk-parity/;backends/robodojo/shared_motion.pyis the worked example), an execution adapter, and calibration for a real robot. A backend-local IK solver or planner needs a written reason, an owner and an expiry beside its code. - Put task identities, suite expansion and source versions in
ora/environment/benchmarks/<sim>.py, and the embodiment's control constants inora/environment/controllers/, which must import without the simulator installed. Simulator imports belong in the worker half only. - Write the worker half: a session class in
ora/environment/backends/<sim>/session.pythat implements the environment session contract (ora/environment/base.py) with public observations, action execution and measured receipts. Register the environment inora/environment/definitions.py(its transports, embodiment, action schemas, capabilities andworker_loader), giveora/environment/worker.pythe branch that builds the session andora/environment/factory.pythe builder that starts the worker. Route every state change through the Supervisor; never expose private evaluator state to the policy.worker.pyandfactory.pyare pinned members of the RoboDojo worker kernel, so this step re-signs the RoboDojo qualification records (repository structure); say so in the pull request. - Write the host half:
ora/orchestrator/backends/<kind>/backend.pydeclaringBACKENDwith its two required hooks (resolve_runtime,preflight_runtime), its capabilities and the optional hooks it needs (qualification, evaluation, play scenes, itsora runcell, itsspecandqualifytools), and an entry inBACKENDSinora/orchestrator/backends/registry.py. The orchestrator core never imports a backend module, so a backend difference becomes a capability or a hook, not a kind check in the core (backends README). - Bind the reviewed embodiment, prompt bundle and ToolSurface, including units, refusal constraints and context projection. If the backend belongs in the default composition, add it to the default baseline (
ora baselines --explainshows the result), describe it underdocs/reference/and add its default RunSpec as a cell ofmatrix()inscripts/dev/compare-model-visible, so later changes are compared on it, in the same pull request. - Add contract tests that drive the session against a fake worker, so they run without the simulator, under
tests/ora/environment/backends/<sim>/andtests/ora/orchestrator/backends/<kind>/. Then run a short episode on the real simulator and state in the pull request the simulator and asset versions, tasks and seeds you ran. Run it again after any change to the controller, the assets or the simulator version; an earlier result does not carry over. - Add a README to each half in the five-section form the other backends use, an environment page under
docs/environments/with installation and a one-task run,ora doctordiscovery of its interpreter and assets, a row in the support matrix, and guidance in the New environment issue template.
Use the Synthetic backend as the reference for transport and lifecycle, and an existing robot backend such as LIBERO for the isolated-interpreter pattern (environment README). Before opening the pull request, run the checks in Contributing: the relevant tests, ./scripts/ora lock when ora/policy/ changed, and scripts/dev/compare-model-visible.