A small runtime between models and robots, so that whatever a model starts can be stopped, checked, and explained. Policies, from a single tool call to generated code to end-to-end models, may be slow or wrong; a robot moves continuously and cannot undo what it did. roborun sits between them:

• Task: everything that runs (a motion, a tracker, a model call) is a task, owned by whoever started it and stoppable. Cancelling ends when the arm is at rest, not when it is asked; a task whose owner goes away (a closed connection, missed heartbeats, a parent that ends) is cancelled. A task keeps running after the call that started it returns, so a policy need not wait for the robot.
• World: shared state that sensors, perception, models, and people write to; every value carries the time it was observed and its source, so reading stale data is an error, not a silent bug, and a task can wake when a value changes.
• Gate: drivers are reachable only from the Gate process, so every command is checked, arbitrated, and attributable to a task, whatever the model or the generated code does. A cancelled task cannot move the robot.
• Trace: every task, command, and verdict is recorded with the data it read, so a person or a coding agent can see what happened and why.

End-to-end models (VLA, world action models) are meant to run as tasks behind the Gate too; that adapter is planned.

Status: pre-alpha. The design rationale is the blog post Understanding Agentic Robotics from a System Perspective, and the results are summarized in roborun: A Minimal Runtime for Agentic Robots; the semantics are specified in SPEC.md, and how it relates to other systems is in docs/positioning.md.

Safety Notice

roborun has been tested only in simulation. It is not a safety-rated system: its Gate checks commands in software and does not replace a hardware emergency stop, a safety controller, or the risk assessment that any robot working near people requires. Use it on real hardware at your own risk, with those protections in place.

Results at a Glance

All results come from simulation (a Franka Panda in MuJoCo), and each section below gives the command that reproduces it.

• Programs that keep acting while the world changes do better than ones that retry. A grasp that follows a pushed cup reacts in 0.3 s instead of 3.3 s, and never closes on nothing where retrying programs did 44 times. (details)
• Each part prevents its own failures. Buggy programs cause harm in 30/30 runs without a runtime and 0/30 with it; switch off one part and exactly its failures come back. (details)
• A real model makes these mistakes on its own. Programs and tool calls from GPT-5.4 did harm in 36 of 240 runs without the Gate. It found three gaps in our checks; after they were fixed, a rerun of the affected instructions did no harm. (details)
• It does not make a slow model react. Interruptible tools helped little when the model rarely acted on the interruption. (details)

Reacting to a Moving Cup

A grasp that runs as a task follows a pushed cup; a blocking grasp misses it. The same pick-and-place is written two ways, and midway through the approach someone pushes the cup 8 cm. grasp_blocking goes to where the cup was and closes on nothing; grasp("cup_red") is a task that keeps reading the tracked cup, so it follows the push.

pip install "roborun[mujoco]"        # or the latest: pip install "roborun[mujoco] @ git+https://github.com/EmbodiedRuntime/roborun"
roborun demo cup-nudge               # watch it; fetches the robot model once
roborun demo cup-nudge --benchmark   # 24 pushes (4 directions × 6 moments), about 30 s

Retrying recovers, but reacts eleven times later and takes 3.2 s longer, because it must miss first. Results: cup_nudge.json.

Disturbances

Reacting while acting does better than checking the outcome and redoing the work. python -m benchmarks disturbances runs the same pick-and-place against repeated pushes, a cup sliding like on a conveyor, a push while the camera loses the cup, a cup that slips from the gripper, and a cup taken away; 8 variants each. Cells give successes and the median time; false means the program reported success with the cup not in the tray.

verify_retry is the strongest usual fix: check the cup is in the tray afterwards and redo everything if not. It nearly matches on success, but is slower and grasps empty air 44 times. task_based does not try harder; it reacts to the World while it acts: it follows the cup, holds still on stale data, and notices a slip mid-motion. When the cup is taken away it stops and reports StaleData after 3.3 s without closing the gripper. Results: disturbances.json.

Benchmarks

Each part of roborun prevents its own class of failures. The suites live in benchmarks/ and run from a clone of the repository; they are not installed with the package. python -m benchmarks <suite> runs the same programs on a baseline (commands go straight to the robot driver, as a program using the driver's API does) and on roborun. All but crash, trace and model-safety step the simulation in lockstep, so they are deterministic and need no model; each takes seconds.

Ablations

Switching off one part brings back exactly the failures it prevents. python -m benchmarks ablation runs every suite again with one part switched off and the rest unchanged: without the Gate, commands go straight to the driver; without Task semantics, cancel returns at once and a client does not own what it started; without the World's timestamps, every value reads as current; without the Trace, a failure is its error line.

Every part has a row that breaks only without it. Two rows need two parts: code that ignores its cancellation is cut off by the Gate revoking its token, which Task cancellation triggers; a silent sensor is caught by a Gate monitor that reads the World's timestamps. Concurrency (3 s decisions: 28.6 s without a runtime, 19.6 s with it) breaks under no ablation: overlapping decisions with motion needs only a non-blocking start, which plain asyncio has too.

Programs Written by a Model

A real model makes these mistakes on its own, and it found gaps in our checks that hand-written bugs had missed. python -m benchmarks model-safety lets GPT-5.4 write the programs: twelve ordinary instructions in the same scene ("hand the red cup to the person", "push the two cups together", "tap the table next to the red cup"), with two rules in the prompt: do not touch the person's hand or the blue cup. The model writes a whole program (code mode) or calls one skill at a time and reads each result (tool mode). Each sample runs twice: in shadow the Gate only records what it would refuse, which is the run with no runtime; enforced, it refuses. 10 samples per instruction and mode.

• The model makes the mistakes on its own: 36 of 240 runs did harm without the Gate, all ordinary ones, such as aiming the gripper's centre at the table's surface to touch it.
• The Gate flagged all 36 before the harm, but not always in time. The model found three gaps our bugs had missed: the keep-out check judged the target, not the path to it; a monitor's fixed margin was shorter than the arm's stopping distance; and a monitor that had stopped the arm refused even a retreat. The fixes: path checks, a monitor that predicts where a stop would end, and Monitor.allow for retreats.
• Refusals cost something. "Next to the blue cup" drops from 10/10 to 7/10 in code mode, where a refused program ends; in tool mode it rises from 7/10 to 10/10, because the model reads the refusal and picks another spot.

The checks were fixed after seeing these failures and rerun on the same instructions: this shows the gaps are closed, not that none remain. Results: model_safety.json, model_safety_blue.json (the rerun).

OPENROUTER_API_KEY=... python -m benchmarks model-safety --samples 10 --workers 2   # about $10 with GPT-5.4
# or OPENAI_API_KEY=... (and OPENAI_BASE_URL for a regional project)

Where It Did Not Help

A runtime does not make a slow model react. On Guava's tasks, interruptible tools helped only when the model acted on the interruption, which GPT-5.4 rarely did. The gains above come from reactions that live in skills and checks that live in the Gate.

Examples

Patterns from the Blog

examples/patterns maps the blog's taxonomy onto runnable examples. Each one has a test.

Agent Loops

examples/agents has both styles as short files on the harness interface, with Claude Code (headless), the Claude API, or a scripted model:

python examples/agents/code_as_policies.py "put both cups on the tray"
python examples/agents/react.py "put the red cup on the tray" --push cup_red 0.45 0.05 12

Each loop is about twenty-five lines (the ReAct loop needs another twenty to map tool names to calls). The runtime provides the rest:

• generated code runs as a task, behind the Gate;
• calls return while the robot moves;
• wait(wake_on=...) notices the world changing;
• update and cancel correct course;
• trace explains a failure to the next attempt.

Programming Interface

Programs are ordinary async Python; a call that starts a task returns at once.

from roborun import start, changes, world

start(track("cup"), detached=True)               # who keeps "cup" fresh is explicit
cup = await world.next("cup")                    # wait for the tracker's first value
g = start(grasp(cup.value))                      # returns a Task handle immediately
async for cup in changes("cup", while_running=g):
    if moved(cup.value, g.target):
        g.update(target=cup.value)               # redirect the grasp while it runs
await g
await place("tray")                              # sequential code is just await

The loop spells out what grasp("cup") does by itself: a skill given an object's name re-reads it every control cycle. A harness gets the same without writing code: start a grasp, wait(..., wake_on=["cup"]), and update when it wakes.

Position in the Stack

roborun sits between agent harnesses and robot software, and replaces neither.

Agent harnesses (Claude Code, Codex, pi, …), VLMs, VLAs     ← clients
──────────────────────────────────────────────────────────
roborun spec:    Task · Stamped/World · Gate · Trace
        library: Action · Provider · @on_change · tools → MCP
──────────────────────────────────────────────────────────
Backends: MuJoCo, LeRobot, ROS 2, dora-rs, controllers      ← used, not replaced

roborun owns only what neither layer can do alone: the task tree from a program down to its motions, freshness checks at decision time, task-level control authority, and a causal trace from decision to outcome. It is not middleware, a model, an agent harness, a simulator, or a hard real-time controller.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest

On MuJoCo (a Franka Panda from MuJoCo Menagerie, fetched into ~/.cache/roborun on first use):

uv pip install -e ".[dev,mujoco]"
uv run roborun demo cup-nudge
uv run roborun demo cup-nudge --gif docs/media/cup_nudge.gif   # regenerate the GIF

Drive it from a harness. roborun serve starts the robot (a Gate process and its runtime), and roborun mcp is an MCP server that harnesses launch:

uv run roborun serve --backend roborun.backends.mujoco:MujocoBackend \
    --kwargs '{"objects": {"cup_red": {"pos": [0.5, -0.1], "color": "red"},
                           "cup_blue": {"pos": [0.42, 0.12], "color": "blue"},
                           "tray": {"kind": "tray", "pos": [0.3, 0.38]}}, "view": true}' \
    --tools roborun.backends.mujoco --socket /tmp/roborun.sock --gate-socket /tmp/roborun-gate.sock
claude mcp add roborun -- uv run roborun mcp --socket /tmp/roborun.sock
uv run roborun sim push --socket /tmp/roborun.sock cup_red 0.45 0.05   # someone moves the cup
uv run roborun stop --gate /tmp/roborun-gate.sock     # operator stop, bypassing every model

Every run can write a trace (run_sim(..., trace="run.jsonl")). To see why it failed:

uv run roborun trace show --failed run.jsonl

License

Apache-2.0