ROSClaw connects AI agents and the physical world. It turns agent intent into governed action, then makes verified physical experience available to memory, reusable skills, and evaluated improvement. Codex, Claude Code, Hermes, OpenClaw, VLAs, and ROSClaw's Native Agent can be clients above it; ROS 2, MCP, simulators, vendor SDKs, and robots connect below it.

Any Agent → ROSClaw → Any Body
             │
             └── Act → Verify → Remember → Evolve

**AI can reason. ROSClaw gives reasoning a governed path into the physical

world—and gives verified experience a path back into intelligence.**

Tongji University · SRIAS

curl -sSL https://rosclaw.io/get | bash
rosclaw firstboot --yes --profile offline --no-telemetry
rosclaw doctor --level verified

Install forms (Alpha). The offline tar bundle is fully self-contained

(Node runtime, npm production deps, Python wheels). The PyPI wheel

(pip install rosclaw) ships the prebuilt agent JS and Python runtime but

requires Node.js ≥ 22.19 on the host — it does not bundle a Node

runtime, and nothing is downloaded at chat time. Rendering additionally

needs a GL backend (OSMesa/EGL/Xvfb); rosclaw doctor reports the exact

OS packages for your platform. We do not claim "zero system dependencies

after pip install" for this release form.

What is ROSClaw?

ROSClaw is the Physical AI Runtime for Embodied Agents: a bidirectional runtime between intelligence and the physical world. It turns intent into governed physical action, and verified physical experience into reusable knowledge. It complements agent frameworks and ROS 2 rather than replacing either. The Native Agent is one optional northbound client.

Its canonical action path binds intent to a body and capability, applies policy and authorization, arbitrates physical resources, dispatches to a driver, and returns an evidence-bearing ExecutionReceipt. Memory and self-evolution are asynchronous, evaluated consumers of that evidence, not substitutes for it.

One Runtime. Two Loops.

| Intelligence → Physical world | Physical world → Intelligence | |---|---| | Intent → Body → Capability → Authority → Action | Observation → Verification → Episode → Memory → Skill → Evolution |

The execution path is governed by the runtime. Practice, memory, and skill evolution build on recorded outcomes; changes still require validation and promotion. Current maturity distinguishes proven paths from experimental work.

Current maturity

ROSClaw is alpha software. The table below is the capability boundary, not a roadmap disguised as completed work.

| Scope | Status | Evidence available today | |---|---|---| | UR5e tabletop reach | Simulation verified | Real MuJoCo execution and receipt verification are system-tested. Local Codex CLI black-box runs discovered all 22 MCP tools, completed the simulation workflow, and confirmed that rosclawd blocks unauthorized REAL actions without hardware dispatch; independent H5 acceptance remains pending. | | rosclawd Agent/physical boundary | Component/system verified | Cross-UID sockets, SO_PEERCRED identity, private state, exact permits, restart recovery, DISARMED generations, Agent Sessions, Action Leases, orphan handling, watchdogs, and isolated worker restart budgets are system-tested; site-specific device ACLs, controller deadman wiring, and hardware acceptance remain pending. | | Action contract and gateway | Component/system verified | Versioned action and receipt, finite deadline and lease, orphan policy, stop capability, strict acknowledgement stages, idempotency, exclusive body lease, and fail-closed executor lookup. | | Capability-only App runtime | Component verified | Local and bundled App manifests, digest-locked installation, low-code authoring, and daemon-only workflow execution are tested; remote App registry and independent Agent acceptance remain pending. | | Generic Hub asset supply chain | Component/system verified | Complete payload hashes, detached Ed25519 signatures, independently scoped trust roots, canonical-reference and copied-manifest binding, target re-verification, bounded extraction, explicit install permissions, owner-only local credentials, and local/file registry lifecycle are system-tested. The packaged trust store is empty; public registry, TUF rollback protection, OS-keyring integration, and builder-attestation verification remain pending. | | E-Stop control path | Component verified | Fan-out, timeout, partial ACK, idempotency, latch, and physical-observation fields; no independent physical-stop verification. | | Mock Sense, mock Providers, fixture Drivers | Fixture only | Explicit FIXTURE and SYNTHETIC data only; never valid for safety or real acceptance. | | RealSense perception-only path | Experimental | A signed, commit-locked RealSense Robot Integration covers install/configure/verify/status, Body binding, daemon-side RGB-D execution, artifact hashing, and bounded MCP subprocess faults; this repository still has no independently verified hardware capture run. | | RH56 LeRobot single-step loop | Developer-observed; revalidation pending | Real SerialModbusTransport, shadow reads, graded REAL actions, and fault injection were developer-observed; a developer Agent black-box (discovery / SHADOW / unauthorized REAL / dataset workflow) passed 2026-07-22 with zero forbidden actions. Loopback fault tests now prove that target-near readback is DELIVERY_INFERRED rather than a protocol ACK. On 2026-07-23 the full v1.0.1 chain was revalidated on the physical RIGHT hand rh56_right_01 — 6/6 register widths declared, measured-envelope calibration, shadow S2 1000 steps, graded REAL noop/micro/motion/gesture/OK all passing (OK 10/10), fault injection 8/8, and an authorized developer agent blackbox executing exactly one permitted noop single step (hardware_actions_executed == 1, PHYSICALLY_OBSERVED). Independent v1 hardware revalidation and independent Agent black-box testing remain open. | | ROS connectors, LeRobot, hardware MCP, real Providers | Experimental | Contract and component coverage varies; registration or import does not imply execution readiness. | | ROS 2 guarded motion (Turtlesim + Gazebo) | Simulation verified | Live rosbridge runs exercised the canonical MCP-to-rosclawd command path. Gazebo Fortress verified a differential-drive body, odometry, laser data, bounded deadman stops, real process kills, rosbridge reconnect with fresh handles, and no replay of an old Action ID. This remains simulation-only; Nav2, independent external-Agent acceptance, and real hardware are not claimed. | | Mobile base continuous-lease deadman | Simulation verified | A MuJoCo mobile base reaches a bounded velocity, loses a 60 ms controller lease, trips its deadman, and reaches below 0.01 m/s with bounded post-loss travel. No physical mobile-base claim is made. | | Repository-wide real robot execution | Revalidation pending | RH56 has developer-run physical evidence, but independent hardware and Agent black-box acceptance are still pending; no repository-wide real-ready claim is made. |

ROS Expert Harness adds runtime system modeling, diagnostics, typed Body readiness and independent mission verification. An isolated Jazzy/Gazebo/Nav2 cleaning mission passed 98.04% coverage with zero physics contacts, with canonical SIM receipts and existing Memory/Practice persistence. Actual-model Native single-input cleaning also passed at 98.01%, with a dynamic obstacle, canonical Memory receipt, Practice SUCCESS and TaskKernel SUCCEEDED. Controlled Agent A/B acceptance remains pending. See implementation evidence.

The core package supports Python 3.11 through 3.13. The isolated LeRobot 0.6 runtime and the bundled RH56 reference-policy plugin require Python 3.12+.

The default install keeps the first verified simulation path lightweight. Install rosclaw[knowledge] when this process should also host the optional Know/How semantic services and their model runtime.

Execution modes

| Mode | Meaning | |---|---| | FIXTURE | Explicit synthetic data. Never verified and never valid for real execution. | | DRY_RUN | Schema/static-policy evaluation; no physical simulation or dispatch. | | REPLAY | Previously recorded evidence; no new physical effect. | | SIMULATION | Physics-backed execution. The UR5e reach path is currently verified. | | SHADOW | Contract defined; no verified golden path yet. | | REAL | Contract defined and fail-closed; no repository-wide real-hardware acceptance claim. |

Why Physical AI Needs Runtime Infrastructure

Large language models can plan, write code, and reason over symbols. But physical intelligence requires more than tokens.

A physical agent must know:

• What body it has;
• What sensors and actuators it owns;
• What actions are safe;
• What happened during execution;
• Why a skill failed;
• How to recover;
• How to improve without breaking safety.

Runtime Loop

Action Intent → Body/Capability → rosclawd Permit/Policy → Resource Lease
              → Dispatch/ACK → Physical Observation → Verification → Receipt
Receipt → Trace/Practice → Memory/How/Auto/Darwin (asynchronous)

**A request is not execution, dispatch is not completion, and completion

requires evidence.**

Auto may propose changes, but it cannot approve them alone. Sandbox validation, Darwin evaluation, the promotion gate, and human approval together decide whether a change reaches the real world.

rosclawd boundary

For Agent-driven physical work, rosclawd is the only supported control-plane entry. MCP and CLI clients submit structured actions over a protected local socket; the daemon independently checks peer/body/snapshot/capability/action intent, Session, expiry, and use count before accepting a permit. Every action has a finite Deadline and renewable Lease; Session loss applies the declared orphan policy. The daemon owns the queue, isolated Adapter workers, physical Runtime, E-Stop latch, watchdogs, and receipts. An authenticated local ledger persists permit consumption and action transitions, restores terminal receipts after restart, and fails closed for interrupted REAL actions pending daemon-UID operator review. A daemon-UID-only CLI can issue one audited, short-lived Permit for an exact Agent proposal; the Agent cannot self-approve it. Every daemon generation starts DISARMED and never resumes an old physical action.

# Development/process-boundary smoke test only
rosclawd --robot-id sim_ur5e
rosclaw daemon status --json
rosclaw daemon session-create --session-id agent-1 --actor-id codex-1 \
  --agent-framework codex --body sim_ur5e --capability sandbox.reach --json
rosclaw daemon security-check --json
Only when status reports recovery.required=true, run as the daemon UID:
rosclaw daemon acknowledge-recovery --reason "reviewed interrupted action evidence" --json

Same-UID development mode is not a hardware privilege boundary. The clean-wheel cross-UID and reference-systemd acceptance scripts verify the generic Linux identity, socket, and private-state boundary. A deployed Agent must additionally pin ROSCLAW_DAEMON_UID to the service account. REAL deployments still require site-specific device ACLs, credential isolation, and SROS2/DDS access control in docs/ROSCLAWD.md. The local HMAC key and signed head detect ordinary tampering and one-sided rollback; they are not a TPM or remote witness against an owner-level attacker who can replace all daemon state.

First Embodiment / Quick Start

Install the CLI and run the interactive first-boot wizard:

curl -sSL https://rosclaw.io/get | bash
rosclaw firstboot
rosclaw doctor --level verified

Run a local simulation demo without any hardware:

rosclaw demo run ur5e-reach
rosclaw explain latest

For headless or CI environments:

rosclaw firstboot --yes --profile offline --no-telemetry

See QUICKSTART.md for four guided paths: local simulation, agent integration, robot body setup, and developer setup.

Robot Integrations

A Robot Integration is the user-facing, signed and versioned onboarding unit above individual Body, Hardware MCP, capability, policy, calibration, and verification assets. Its internal manifest remains RobotPack; it is an asset bundle, not another execution framework. The first built-in Integration supports perception-only RealSense D405/D435i onboarding:

rosclaw robot discover --type camera --json
rosclaw robot install ros-claw/realsense-d400
rosclaw robot verify realsense-d400 --stage contract
rosclaw robot configure realsense-d400 --instance lab-d405 --serial SERIAL

Add --install-adapter only when the host should install the Integration's native MCP dependencies at its locked commit. Installation and offline configuration are not hardware verification. H3 additionally requires complete live identity, stream profiles, real RGB-D artifacts and hashes, a canonical rosclawd receipt, and independent physical observation.

See docs/ROBOT_PACKS.md for trust, daemon loading, support tiers, and the hardware acceptance procedure.

Capability Apps

Apps are small capability-only task manifests. They never name device paths, registers, ROS command topics, or Adapter APIs, and every step is submitted through rosclawd:

rosclaw app install ros-claw/realsense-inspect
rosclaw app validate realsense-inspect --json
rosclaw app run realsense-inspect --body lab-d405 --mode SHADOW --json

The bundled realsense-inspect and rh56-rps manifests are component-tested. This does not claim a verified camera capture or RH56 Agent run: RealSense H3 still needs independent hardware evidence, and RH56 production Robot Integration/Worker migration is still pending. See docs/APPS.md.

Core Runtime Modules

| Module | Responsibility | |---|---| | Runtime | Lifecycle, configuration, plugin registration, dependency injection. | | EventBus | Module communication, topic routing, trace correlation. | | Provider | Capability routing, schema enforcement, safety boundary. | | Sandbox | Safety validation, firewall, MuJoCo pre-play. | | Practice | Timeline capture, MCAP, JSONL, execution records. | | Memory | Experience graph, failure/success patterns, recall. | | Know | TaskCard, Pattern, EvidenceTrace, failure taxonomy. | | How | Runtime intervention, injection ID, evidence-backed repair. | | Auto | Proposal, patch, experiment, champion, dead-end tracking. | | Darwin | Multi-seed benchmark, stress scenario, regression. | | Skill Registry | Version, lineage, champion, rollback. | | Dashboard | Observability, evolution trace, lineage visualization. |

Structured Runtime Trace

ROSClaw records a causal span tree across Runtime, Provider, MCP, Skill, Sandbox, and Firewall boundaries. Model/tool I/O is bounded and redacted, binary perception data is stored as references, and private chain-of-thought fields are omitted by default in favor of structured decision summaries.

rosclaw trace list
rosclaw trace show <trace-id> --tree
rosclaw trace tail --kind VLM,MCP,SANDBOX
rosclaw dashboard --trace <trace-id>

The built-in Trace view is available at /traces.

See docs/TRACE.md for the schema, instrumentation API, capture modes, CLI, and Dashboard endpoints.

Hub & Assets

Teach Once. Embody Anywhere. Skills capture reusable behavior; a new body still requires capability matching and validation before execution.

The generic ROSClaw Hub is a Physical-AI developer asset pipeline for skills, providers, hardware MCP servers, digital twins, and cognitive wikis. It now enforces complete payload hashes, detached Ed25519 signatures, independent scoped trust roots, and safe archive extraction. Its registry is still local/file-backed; this is not yet a supported public asset registry and is separate from the existing rosclaw mcp discovery service.

Supported asset types:

• skill — reusable physical-AI skill
• provider — runtime capability provider
• hardware_mcp — MCP server that wraps real hardware
• digital_twin — simulation asset / e-URDF twin
• cognitive_wiki — structured operational knowledge

rosclaw hub validate tests/fixtures/hub_assets/hardware_mcp_valid/manifest.yaml
rosclaw hub search g1
rosclaw hub verify tests/fixtures/hub_assets/hardware_mcp_valid \
  --trust-store tests/fixtures/hub_keys/trust.json
rosclaw hub install tests/fixtures/hub_assets/hardware_mcp_valid --dry-run \
  --trust-store tests/fixtures/hub_keys/trust.json --allow-real-robot

The committed trust key is test-only. Production trust roots must be provisioned independently; the packaged trust store is intentionally empty.

See docs/ASSETS.md and docs/hub/README.md.

Hardware MCP Onboarding

ROSClaw can auto-install hardware MCP servers from declarative manifests and keep them healthy. Manifests resolve in this order:

1. Local cache under ~/.rosclaw/mcp/cache/.
2. Built-in offline registry (unitree-g1, realsense-d455, ...).
3. Remote ROSClaw Hub at https://www.rosclaw.io/api/registry.

Quick start

# Preview what an install would do (no changes written)
./rosclaw mcp install unitree-g1 --dry-run --offline
Install a built-in hardware MCP without touching the network
./rosclaw mcp install unitree-g1 --offline
Preview a public Hub package (remove --offline to fetch from the network)
./rosclaw mcp install ros-claw/g1-mcp --dry-run --offline
Use a private/custom hub endpoint
ROSCLAW_MCP_HUB=https://my-hub.example.com ./rosclaw mcp install ros-claw/g1-mcp --dry-run --offline
List installed and available servers
./rosclaw mcp list --offline
./rosclaw mcp list --offline --json
Health-check installed servers
./rosclaw mcp health
./rosclaw mcp health unitree-g1
./rosclaw mcp health unitree-g1 --full --json

Use --dry-run to inspect the resolved manifest, version, artifact, body patch, permissions, and Claude .mcp.json merge plan before writing anything. Use --offline to force local-only resolution (cache + built-ins).

See docs/HARDWARE_MCP_ONBOARDING.md for the full lifecycle, state files, permissions, and troubleshooting.

Install and Configure ROSClaw for Any Agent

Paste this setup prompt into Codex, Claude Code, OpenClaw, or another MCP-aware agent:

Install and configure ROSClaw for this repository. Run

rosclaw agent install --project-root . --skip-secrets, then read

ROSCLAW.md, AGENTS.md, .codex/config.toml, and

.agents/skills/rosclaw/SKILL.md. Validate

the setup with rosclaw agent test universal --project-root . --quick

--mcp-probe. For Codex, reopen this exact repository and accept workspace

trust; for Claude Code, approve the project-scoped rosclaw MCP server.

After that, use ROSClaw through its CLI and MCP tools for robot

state, skills, memory, sandbox simulation, practice records, and safety

checks. For physical work, use only the daemon-backed request_action,

action-status, cancellation, and emergency tools; never open a device or

publish a command topic directly.

If you are doing the setup yourself, the core install command is:

rosclaw agent install --project-root . --skip-secrets

This installs and configures the agent-facing ROSClaw integration files: .mcp.json, .codex/config.toml, AGENTS.md, ROSCLAW.md, CLAUDE.md, .agents/skills/rosclaw/SKILL.md, and .rosclaw/agent/context.snapshot.json.

It does not install ROSClaw itself and does not install a native plugin for one specific agent framework. ROSClaw remains an independent CLI, Python package, MCP server, and robotics infrastructure layer; this command teaches agent harnesses how to discover and use it. Claude Code receives .mcp.json, Codex receives a trusted-project .codex/config.toml, and OpenClaw discovers the workspace skill under .agents/skills.

The installer cannot bypass harness security prompts. Codex ignores the project .codex/config.toml until the exact Git repository root is trusted; check it with rosclaw agent doctor codex --project-root .. Claude Code shows the project server as pending until the user approves it; check it with claude mcp get rosclaw.

Run the MCP probe from the same environment and PATH used to launch the Agent. The probe executes the configured rosclaw command and requires the exact 22-tool boundary, so an older global CLI cannot silently pass by using the source checkout's Python process.

Persist Practice to SeekDB

Use SQLite for local development or a MySQL-compatible DSN for a real SeekDB/OceanBase server:

When --data-root is omitted, ROSClaw uses ROSCLAW_PRACTICE_DATA_ROOT when set, otherwise $ROSCLAW_HOME/data/practice (default ~/.rosclaw/data/practice). Container deployments can explicitly set the environment variable to /data/rosclaw/practice.

# Local file
rosclaw practice ingest-seekdb <practice_id> \
  --seekdb-path ~/.rosclaw/memory/seekdb.sqlite
Real SeekDB server
rosclaw practice ingest-seekdb <practice_id> \
  --seekdb-url mysql://[email protected]:2881/rosclaw
rosclaw practice query failures \
  --robot-id rh56 \
  --seekdb-url mysql://[email protected]:2881/rosclaw \
  --json

SeekDB port 2881 uses the MySQL-compatible SQL protocol. It is not an HTTP API. Repeated Practice ingestion is idempotent by episode and evidence IDs.

Safety Model

ROSClaw's core safety rule:

No model output should directly control a robot.

The new canonical physical-action path is:

1. Provider produces a structured action proposal.
2. Sandbox / Firewall checks it against the effective body model and safety policy.
3. The decision is one of ALLOW, MODIFY, BLOCK, or REQUIRE_HUMAN_CONFIRMATION.
4. rosclawd authenticates the peer and matches an expiring, use-bounded permit

1. ActionGateway acquires an exclusive resource lease and dispatches a daemon-owned executor.
2. Driver ACK, observations, verification, trace, and artifacts are assembled into a receipt.
3. Practice, Memory, How, Auto, and Darwin may consume the receipt asynchronously.

The known MCPHub low-level actions, standalone UR5 MCP motion tools, and ROS connector capability execution now fail closed instead of dispatching directly. The ROS connector still supports discovery, validation, explicit dry runs, and daemon-backed emergency-stop request receipts while its executors are migrated.

ROSClaw is research infrastructure. It does not replace certified industrial safety systems. Always test in simulation first, keep emergency stops engaged, and use human supervision.

Read docs/SAFETY.md for the full safety model.

Documentation

• QUICKSTART.md — 5-minute quick start.
• INSTALL.md — Detailed installation and troubleshooting.
• docs/FIRSTBOOT.md — Bootstrap and first boot reference.
• docs/CLI.md — CLI command reference.
• docs/SAFETY.md — Safety model and deployment rules.
• docs/ROSCLAWD.md — Agent/physical process and privilege boundary.
• docs/ASSETS.md — Physical-AI Asset Hub.
• ARCHITECTURE.md — Runtime architecture.
• CONTRIBUTING.md — Development standards.

Roadmap

| Phase | Focus | |---|---| | Current / Alpha | rosclawd process boundary and durable local control ledger, truthful action/receipt contracts, fail-closed fixtures/providers/drivers, MuJoCo UR5e Reach and ContactPush failure-to-success simulation paths, ROS 2 Turtlesim/Gazebo guarded motion, and readiness-level Doctor. | | Next | Migrate every remaining physical side-effect path to the gateway; ledger compaction/external witnessing; general cancellation/preemption; Nav2 and independent external-Agent acceptance. | | Hardware acceptance | RealSense read-only capture, then bounded actuator tasks with ACK, feedback, stop verification, and receipts. | | Later | Body-aware skill adaptation, active perception, and broader independently maintained multi-task simulation benchmarks. |

Contributing

We welcome contributions. See CONTRIBUTING.md for standards, PR process, and code style.

Contact

• Email: [email protected]
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT