Quickstart

Install OmniLoop, bring up the dashboard, and drag sliders that control a running process — in under 5 minutes.

OmniLoop spans two jobs with one tool: tune the reward and catch the collapse while a policy trains, then keep the same tripwires armed when it runs on the machine. This page is the first one; C++ and Rust are the second.

Is OmniLoop for me?Neither job describes your work? The engine has no concept of a robot or a reward — five preconditions decide whether it helps you, and they are not about your field.

Install

pip (recommended)

pip install omniloop

Pull in only the framework extras you need:

pip install omniloop[sb3]              # Stable-Baselines3
pip install omniloop[tensorboard]      # TensorBoard mirror
pip install omniloop[rerun]            # Rerun sink
pip install omniloop[all-integrations] # everything

From source

# Requires a Rust toolchain + maturin
pip install maturin
cd omniloop-sdk-python && maturin develop

Note

pip install omniloop is all you need. The wheel carries the telemetry server and a prebuilt dashboard, so omniloop up works from any directory — no repository checkout, no Node, no npm install.

In a checkout, omniloop up prefers the Vite dev server instead, so dashboard edits hot-reload. Set OMNILOOP_DASHBOARD_DIR to serve a bundle from somewhere else.

Bring up the dashboard

1. Start the visualizer — one command replaces the old two-terminal dance:

   omniloop up

   From a pip install this serves both the telemetry server and the dashboard on :8000. From a repository checkout it additionally starts the Vite dev server on :5173 and points you there, so dashboard changes hot-reload.

2. Run a target loop — in a second terminal, start the bundled demo:

   omniloop demo

   It ships in the wheel, so there is nothing to clone. From a checkout you can equally run any of examples/, e.g. python examples/rl/mock_rl_training.py.

3. Open the dashboard — navigate to the URL omniloop up printed: http://localhost:8000 for a pip install, or http://localhost:5173 when the dev server is running.

Drag a slider

The dashboard’s Interactive State Matrix shows sliders for every tunable parameter. Drag learning_rate — you’ll see the mock training loop’s reward_mean react in real time.

That’s it. The loop is running, and you’re editing its live state without restarting it.

What just happened

┌──────────────┐     shared memory      ┌──────────────┐     websocket     ┌──────────────┐
│  Your Loop   │ ◄──────────────────── │  OmniLoop    │ ◄───────────────► │  Dashboard   │
│  (Python)    │  telemetry + commands  │  Server      │   telemetry +    │  (React)     │
│              │ ────────────────────► │ (Starlette)  │   mutations      │              │
└──────────────┘                        └──────────────┘                    └──────────────┘

1. Your loop registers variables and publishes telemetry through shared memory (Rust IPC, no sockets in the hot path).
2. The server polls the shared-memory channel and rebroadcasts over a WebSocket.
3. The dashboard renders the state and sends mutation commands back.
4. Mutations arrive in the loop’s next tick() / wait_if_halted() call — applied instantly.

Plug in your own code

The fastest path is TrainingLoop — it derives the dashboard schema from your existing config dataclass, and binds each parameter back to the object that actually owns it:

from omniloop import TrainingLoop

loop = TrainingLoop.from_dataclass(
    cfg.ppo,
    tunable=["entropy_coef", "clip_param", "learning_rate"],
    bind={"learning_rate": optimizer},   # writes optimizer.param_groups[*]["lr"]
    journal="run.omni",
)
loop.watch_all_nonfinite(True)           # freeze on the first NaN, don't crash

for it in range(num_iterations):
    with loop.tick():
        train_one_iteration(...)
        loop.log(reward_mean=r, policy_loss=pl)

Bind the thing you actually iterate on

On a robot, that is rarely the learning rate — it is gains, thresholds and envelope limits: the values you would otherwise change by editing a YAML file and relaunching, losing a warm motor and a settled thermal state each time.

If your framework already has a loop you can’t restructure, use a framework adapter instead:

Framework	Integration
ROS 2	OmniLoopRosBridge
LeRobot	OmniLoopCallback
MuJoCo	Built-in MujocoAdapter

An adapter earns its place by answering one of two questions the SDK cannot answer for itself: where is the tick, in a loop you do not own, and where is the variable, in a foreign object model. New adapters are pulled by a named user rather than pushed speculatively.

Useful commands

omniloop up                     # start server + dashboard
omniloop up --session my_run    # isolated session
omniloop status                 # live / stale / absent, plus server health
omniloop doctor                 # diagnose channel health & publisher collisions
omniloop clean --dry-run        # show which stale /dev/shm segments would go

omniloop inspect run.omni       # summary of a recorded .omni journal
omniloop replay run.omni --events-only     # step through what happened
omniloop why run.omni --tick 4350          # the causal chain behind a tick
omniloop diff recorded.omni replayed.omni  # first tick where two runs disagree
omniloop export-mcap run.omni   # export to .mcap (Foxglove, Rerun, ROS 2)

omniloop mcp                    # MCP server: let an AI agent drive the control plane

Full flag and exit-code reference: CLI Reference.

Next steps

Integration GuidesWire up your framework in one call.

TrainingLoop APIFull reference for the recommended API.

Halt & StepUnderstand the execution control model.

Journals & ReplayRecord and replay training runs.

MCP ServerHand the control plane to an AI agent — read-only by default.