English | 简体中文

<p align="center"> <img src="https://raw.githubusercontent.com/dora-rs/dora/main/docs/src/logo.svg" width="400"/> </p> <h2 align="center"> <a href="https://www.dora-rs.ai">Website</a> | <a href="https://dora-rs.ai/docs/guides/getting-started/conversation_py/">Python API</a> | <a href="https://docs.rs/dora-node-api/latest/dora_node_api/">Rust API</a> | <a href="https://www.dora-rs.ai/docs/guides/">Guide</a> | <a href="https://discord.gg/6eMGGutkfE">Discord</a> </h2> <div align="center"> <a href="https://github.com/dora-rs/dora/actions"><img src="https://github.com/dora-rs/dora/workflows/CI/badge.svg" alt="Build and test"/></a> <a href="https://crates.io/crates/dora-cli"><img src="https://img.shields.io/crates/v/dora-cli.svg" alt="crates.io"/></a> <a href="https://docs.rs/dora-node-api/latest/dora_node_api/"><img src="https://docs.rs/dora-node-api/badge.svg" alt="docs.rs"/></a> <a href="https://pypi.org/project/dora-rs/"><img src="https://img.shields.io/pypi/v/dora-rs.svg" alt="PyPI"/></a> <a href="https://github.com/dora-rs/dora/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dora-rs/dora" alt="License"/></a> </div>

Dora

Agentic Dataflow-Oriented Robotic Architecture -- a 100% Rust framework for building real-time robotics and AI applications.

User Guide | 用户指南 (中文)

Built and maintained with agentic engineering -- AI agents do the heavy lifting on code generation, reviews, refactoring, and testing; humans set direction and gate every merge.

---

Table of Contents

• Features
• Installation
• Quick Start
• CLI Commands
• Dataflow Configuration
• Architecture
• Language Support
• Examples
• Development
• Contributing
• License

Features

Performance

• 10-17x faster than ROS2 Python -- 100% Rust internals with zero-copy shared memory IPC for messages >4KB, flat latency from 4KB to 4MB payloads
• Zenoh SHM data plane -- nodes publish directly via Zenoh shared memory, bypassing the daemon for 35% lower latency and 3-10x higher throughput on large payloads; automatic network fallback for cross-machine
• Apache Arrow native -- columnar memory format end-to-end with zero serialization overhead; optional Arrow IPC framing for self-describing wire format; shared across all language bindings
• Non-blocking event loop -- Zenoh publishes offloaded to a dedicated drain task; control commands respond in <500ms even under high data throughput

Developer experience

• Single CLI, full lifecycle -- dora run for local dev, dora up/start for distributed prod, plus build, logs, monitoring, record/replay all from one tool
• Declarative YAML dataflows -- define pipelines as directed graphs, connect nodes through typed inputs/outputs, optional type annotations with static validation, override with environment variables
• Multi-language nodes -- write nodes in Rust, Python, C, or C++ with native APIs (not wrappers); mix languages freely in one dataflow
• Reusable modules -- compose sub-graphs as standalone YAML files with typed inputs/outputs, parameters, optional ports, and nested composition (compile-time expansion, zero runtime overhead)
• Hot reload -- live-reload Python operators without restarting the dataflow
• Programmatic builder -- construct dataflows in Python code as an alternative to YAML

Production readiness

• Fault tolerance -- per-node restart policies (never/on-failure/always), exponential backoff, health monitoring, circuit breakers with configurable input timeouts
• Distributed by default -- local shared memory between co-located nodes, automatic Zenoh pub-sub for cross-machine communication, SSH-based cluster management with label scheduling, rolling upgrades, and auto-recovery
• Coordinator HA -- persistent redb-backed state store (default), daemon auto-reconnect with exponential backoff, dataflow records survive coordinator restart (running dataflow reclaim-across-restart is partial, see the open issue tracker)
• Dynamic topology -- add and remove nodes from running dataflows via CLI (dora node add/remove/connect/disconnect) without restarting
• Soft real-time -- optional --rt flag for mlockall + SCHED_FIFO; per-node cpu_affinity pinning in YAML; comprehensive tuning guide for memory locking, kernel params, and container deployment
• OpenTelemetry -- built-in structured logging with rotation/routing, metrics, distributed tracing, and zero-setup trace viewing via CLI

Debugging and observability

• Record/replay -- capture dataflow messages to .drec files, replay offline at any speed with node substitution for regression testing
• Topic inspection -- topic echo to print live data, topic hz TUI for frequency analysis, topic info for schema and bandwidth
• Resource monitoring -- dora top TUI showing per-node CPU, memory, queue depth, network I/O, restart count, and health status across all machines; --once flag for scriptable JSON snapshots
• Trace inspection -- trace list and trace view for viewing coordinator spans without external infrastructure
• Dataflow visualization -- generate interactive HTML or Mermaid graphs from YAML descriptors

Ecosystem

• Communication patterns -- built-in service (request/reply), action (goal/feedback/result), and streaming (session/segment/chunk) patterns via well-known metadata keys; no daemon or YAML changes required
• ROS2 bridge -- bidirectional topics, services, and actions over DDS or native rmw_zenoh_cpp-compatible Zenoh; QoS mapping; Arrow-native type conversion
• Node Hub (package manager) -- pull a reusable node into a dataflow with one line -- hub: dora-yolo@^0.5 -- with cargo-style versioned resolution, reproducible lockfiles (--locked), and typed contracts checked at build time; backed by a git-based public catalog of ready-made nodes for cameras, YOLO, LLMs, TTS, and more. See the Hub guide (unstable)
• In-process operators -- lightweight functions that run inside a shared runtime, avoiding per-node process overhead for simple transformations

Installation

From crates.io (recommended)

cargo install dora-cli           # CLI (dora command)
pip install dora-rs              # Python node/operator API

From source

git clone https://github.com/dora-rs/dora.git
cd dora
cargo build --release -p dora-cli
PATH=$PATH:$(pwd)/target/release

# Python API (requires maturin >= 1.8: pip install maturin)
# Must run from the package directory for dependency resolution
cd apis/python/node && maturin develop --uv && cd ../../..

Platform installers

macOS / Linux:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/dora-rs/dora/releases/latest/download/dora-cli-installer.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://github.com/dora-rs/dora/releases/latest/download/dora-cli-installer.ps1 | iex"

Build features

| Feature | Description | Default | |---------|-------------|---------| | tracing | OpenTelemetry tracing support | Yes | | metrics | OpenTelemetry metrics collection | Yes | | python | Python operator support (PyO3) | No | | redb-backend | Persistent coordinator state (redb) | Yes |

cargo install dora-cli --features redb-backend

Quick Start

1. Run a Python dataflow

Important: The PyPI package is dora-rs, not dora. The import name is dora (from dora import Node), but pip install dora installs an unrelated package.

cargo install dora-cli            # or use install script below
pip install dora-rs numpy pyarrow
git clone https://github.com/dora-rs/dora.git && cd dora
dora run examples/python-dataflow/dataflow.yml

This runs a sender -> transformer -> receiver pipeline. Here's what the Python node code looks like:

# sender.py -- sends messages and polls for STOP
from dora import Node
import pyarrow as pa
import time

node = Node()
sent = 0
while sent < 100:
    event = node.try_recv()
    if event is not None and event["type"] == "STOP":
        break
    node.send_output("message", pa.array([sent]))
    sent += 1
    time.sleep(0.1)

# receiver.py -- receives and prints messages
from dora import Node

node = Node()
for event in node:
    if event["type"] == "INPUT":
        print(f"Got {event['id']}: {event['value'].to_pylist()}")
    elif event["type"] == "STOP":
        break

See the Python Getting Started Guide for a full tutorial, or the Python API Reference for complete API docs.

2. Run a Rust dataflow

cd examples/rust-dataflow
dora run dataflow.yml

3. Distributed mode (ad-hoc)

# Terminal 1: start coordinator + daemon
dora up

# Terminal 2: start a dataflow (--debug enables topic inspection)
dora start dataflow.yml --attach --debug

# Terminal 3: monitor
dora list
dora logs <dataflow-id>
dora top

# Stop or restart
dora stop <dataflow-id>
dora restart --name <name>
dora down

4. Managed cluster

# Bring up a multi-machine cluster from a config file
dora cluster up cluster.yml

# Start a dataflow across the cluster
dora start dataflow.yml --name my-app --attach

# Check cluster healt