§ Getting started · one line APRIL 21, 2026

Configure your robot for Claude Code.
One file. One robot.

~/bob · robot-md v0.6.3 ● one command · manifest + MCP + skill + auto-calibrate + arm.pick
$pip install robot-md && robot-md init

🤖 robot-md v0.6.3
? Name your robot: [bob] bob
? Scan for hardware? [Y/n] y
→ scanning /dev/tty* ... found Feetech bus (6 servos)
→ scanning USB ... found OAK-D camera
★ Auto-matched preset: so-arm101
? Register with Robot Registry Foundation (RRF)? [Y/n] y
? Manufacturer / Organization: Acme Corp
→ minting RRN ... RRN-000000000173
→ validating manifest ... 55/55 valid
? Install MCP server for Claude Code? [Y/n] y
→ claude mcp add robot-md
→ installing using-robot-md skill ... ok
? Calibrate arm zero pose now? [Y/n] y
→ move arm to zero and press Enter... ok
→ auto-calibrated ready pose via IK
▸ hint: run claude to start planning.
$claude
› bob is online. ready pose auto-calibrated. What should I pick?
pick the red lego and place it in the bowl
ROBOT.md
v0.6.3 · The CLAUDE.md and AGENTS.md for physical machines. One command wires up a single robot to Claude Code via the robot-md MCP server. While purpose-built for Anthropic's surfaces, ROBOT.md is an open standard that any AI agent can use to understand and safely operate a robot.
How it works →
§ 01 — The file itself

A robot is what its ROBOT.md says it is.

Every robot today drifts across five files — a YAML config, a P66 manifest, a CLAUDE.md, a firmware manifest, a README. Add a joint, update three. Miss one, ship a lie. ROBOT.md collapses the stack into a single source of truth.

bob.ROBOT.md VALID · RCAN 3.0 
---
rcan_version: "3.0"
metadata:
  robot_name: bob
  rrn:        RRN-000000000003
  manufacturer: craigm26
physics:
  type: arm+camera
  dof:  6
drivers:
  - { id: arm,    protocol: feetech, port: /dev/ttyUSB0 }
  - { id: camera, protocol: depthai, model: OAK-D       }
capabilities:
  - arm.pick
  - arm.place
  - vision.describe
  - status.report
safety:
  payload_kg: 0.5
  estop:      { software: true, response_ms: 100 }
  hitl_gates:
    - { scope: destructive, require_auth: true }
brain:
  planning:  { provider: anthropic, model: claude-opus-4-7 }
---

# bob

## Identity
Bob is a 6‑DOF SO‑ARM101 arm with an OAK‑D camera. Stationary,
reach ≈ 60 cm, payload ≤ 0.5 kg. RRN‑000000000003.

## What bob Can Do
Pick, place, describe what the camera sees. Arm only — no
navigation. Inverse kinematics handled by the runtime.

## Safety Gates
Software E‑stop, 100 ms. Destructive actions route through
RCAN §8 AUTHORIZE. Bounds enforced per‑joint before servo bus.
§ 02 — The stack

Four layers. Built for Claude Code, powered by open standards.

ROBOT.md declares what the single robot is to Claude Code. To ensure safety and verifiable identity, it strictly requires two independent foundations: RCAN (the signed wire protocol) and the Robot Registry Foundation (RRF) (permanent identity). OpenCastor (visual editor) is optional. Tier 0 runtime is Claude Code itself.

Layer 4 · DeclarationROBOT.md
This specYAML + markdown. One file at the robot's root. Read at session start by the planner; consumed by every layer below.
FormatFrontmatter validated by JSON Schema draft 2020‑12. Body read by Claude Code, Desktop, Mobile.
StatusDraft v1 shipped 2026‑04‑21. v1.0 frozen spec targeted Q3 2026.
Layer 3 · ProtocolRCAN 3.0+
WireSigned envelopes between planner, gateway, and driver. Level‑of‑Assurance enforcement on every call. Manifests declare rcan_version: "3.0" — minor-version increments (3.1, 3.2, …) are backward-compatible.
CryptoPQC‑primary: ml-dsa-65 at L2+. Ed25519 accepted at L1 only, sunset mid‑cycle. Per-manifest via network.signing_alg.
Compliance§23–§27 cover EU AI Act Annex III audit trails, FRIA refs, ISO 42001 self‑assessment.
Layer 2 · RegistryRobot Registry Foundation
IdentityAssigns an RRN — a permanent, globally‑unique robot identifier. Mint with one command: robot-md register ROBOT.md. Resolvable via rrn:// URIs.
NeutralA foundation, not a vendor. Cloudflare Pages + Workers + D1. No seat fees, no per‑robot tax.
PublicPublic endpoint at rcan.dev/r/<rrn>. Self‑hosted mode supported.
Layer 1 · RuntimeClaude Code is enough. OpenCastor for harness authoring & swarms.
Tier 0Claude Code is already a runtime. Drop ROBOT.md in a repo with shell access to your robot — USB, serial, HTTP, MQTT — and the Bash tool dispatches. No SDK to install.
Tier 1Add your own driver scripts for sub‑second loops. Still no "runtime" in the traditional sense — just Claude plus the scripts you'd write anyway.
Tier 2OpenCastor — a visual agent-harness editor plus multi-robot swarm orchestration. ROBOT.md is its native robot format, but Claude Code reads the same file standalone. Opt-in when you need to compose harnesses visually or run a fleet.
Layer 3 · Wire protocol

RCAN 3.0+ — Robot Communication & Addressing Network

An open protocol that lets robots, gateways, and planners exchange signed, authority‑aware messages without vendor coupling. A strict requirement for any valid ROBOT.md.

  • Signed envelopes with ML‑DSA‑65 primary + Ed25519 legacy (L1 only, sunset mid‑cycle).
  • Level‑of‑Assurance ladder — every call is classified L0 / L1 / L2, enforced gateway‑side.
  • Section 8: AUTHORIZE message for human‑in‑the‑loop gates declared in ROBOT.md.
  • Sections 23–27: EU AI Act Annex III audit trails, FRIA URI binding, ISO 42001 self‑assessment.
  • Published and version‑tagged at rcan.dev. Apache‑2.0. Governed by the RCAN working group.
rcan.dev → read the protocol spec
Layer 2 · Registry

Robot Registry Foundation — permanent, neutral robot identity

RRF issues an RRN (Robot Registration Number) the same way a VIN identifies a car — one robot, one number, forever. A strict requirement for any valid ROBOT.md.

  • RRN format: RRN‑000000000001 (12‑digit numeric) and rrn://org/category/model/id URI form.
  • Public resolver at rcan.dev/r/<rrn> — returns the robot's ROBOT.md, its compliance block, its registry metadata.
  • Mint in one command: robot-md register ROBOT.md reads your manifest's metadata.manufacturer/model/version/device_id, POSTs to RRF, and writes the assigned RRN back into the file.
  • Edge‑served via Cloudflare Pages + Workers + D1. Zero downtime at the identifier layer.
  • Foundation‑governed, not vendor‑owned. Self‑hosted mode for private fleets.
  • RRF is the authority ROBOT.md points at when metadata.rrn_uri is populated.
robotregistryfoundation.org → register a robot

Claude Code is already a runtime. ROBOT.md is the file that makes it a robot runtime.

§ 03 — Claude, three surfaces (and every other MCP‑aware harness)

Wherever the planner runs, the robot is legible.

A ROBOT.md is meant to be picked up by a planning LLM at the start of every session. Purpose-built for Anthropic: the same file, the same MCP server, works seamlessly with Claude Code, Claude Desktop, and Claude Mobile. Flexible for everyone: much like CLAUDE.md and AGENTS.md, any AI agent or planner (OpenAI, Gemini, Cursor, Cline) can consume this format to operate a robot safely.

● Shipping

Claude Code · CLI

Zero flags. robot-md init — Claude Code drives the rest.

Built for operators at a terminal. pip install robot-md && robot-md init autodetects your hardware, picks the right preset, writes ROBOT.md and CLAUDE.md, installs the robot-md MCP server, and drops the using-robot-md skill. Open Claude Code next and the planner reads your robot's frontmatter, capabilities, safety gates, and prose body as MCP resources. Claude asks follow-ups — register? calibrate zero? hand-eye? — in English.

Two commands. Zero flags. Claude Code recognizes the robot.
● Shipping

Claude Desktop · macOS / Windows

One command. robot-md install-desktop ROBOT.md

Merges a robot-md entry into claude_desktop_config.json on the right OS path (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%/Claude/), preserving any other MCP servers. Restart Claude Desktop and the full MCP surface loads: the same 6 resources, 3 tools (validate, render, doctor_summary), and 4 slash commands — /check-safety action="…" gates motion before a driver ever moves.

Idempotent · --force to replace · safe with existing servers
● Shipping

Claude Mobile · iOS / Android

URL fetch. Paste the manifest URL into the chat.

iOS has no local MCP, but it fetches URLs and reasons over what it finds. Host ROBOT.md + .well-known/robot-md.json at any public HTTPS URL (GitHub Pages works today), paste the link, and Claude Mobile answers from the manifest. The auto-generated CLAUDE.md makes the safety posture explicit so the gate-check logic survives the trip to mobile. Use robot-md publish-discovery ROBOT.md --url <URL> to emit the discovery doc.

Works today · no native app · no Anthropic change
§ 04 — Field reference

The frontmatter, in one table.

Excerpted from spec v1 §3. Full normative text, JSON Schema, and extension rules live in the repo.

Field Type Required Purpose
rcan_version string ✓ RCAN wire-protocol version — "3.0" covers the 3.x line. 2.1+ accepted; 1.x rejected for EU AI Act gap. See rcan.dev/spec.
metadata.robot_name string ✓ Short display name. Must match the body H1. Used in every planner citation.
metadata.rrn string ✓ RRF-assigned identifier (e.g. RRN-000000000001). Empty until robot-md register mints one. Resolves via rcan.dev/r/<rrn>.
metadata.rrn_uri string — Optional URI form: rrn://<org>/<category>/<model>/<id> — dereferenceable by any RCAN-aware client.
physics.type enum ✓ arm · wheeled · tracked · legged · arm+camera · humanoid · sensor · other
physics.dof int ✓ Degrees of freedom. 0 permitted for purely sensory nodes.
physics.kinematics[] array ★ Per-joint geometry. Each entry: id, axis (x/y/z), a_mm/d_mm DH params, limits_deg, servo_id, encoder_sign, zero_pose_steps.
physics.solver map — Baseline FK/IK config so any planner can reach a target from the manifest alone — no URDF, no MoveIt. Fields: convention, base_frame, encoder.steps_per_rev, gripper (tip offset, open/close steps), camera (mount + extrinsic).
drivers[] array ✓ At least one. Each declares id + protocol (feetech, dynamixel, depthai, ros2, …).
capabilities[] array ✓* Required when dof > 0. Namespaces: nav.*, arm.*, vision.*, status.*, system.*, vendor <prefix>.*.
safety.estop map ✓ At minimum: software: true + response_ms. Hardware button recommended for Annex III systems.
safety.hitl_gates array ★ Scopes (destructive, system, …) that require human authorization via RCAN §8 AUTHORIZE.
brain map ★ Planner + reactive model declaration. Task‑routing overrides. Required if the robot uses an LLM in the loop.
network.rrf_endpoint string ✓ RRF resolver — defaults to https://robotregistryfoundation.org. Serves the signed manifest at /r/<rrn> and FRIA at /api/v1/robots/<rrn>/fria.
network.signing_alg string ✓ RCAN 3.0 primary: ml-dsa-65 (PQC). ed25519 accepted at Level-of-Assurance 1 only; sunset mid-3.x.
compliance map ✓ FRIA URI, ISO 42001 self‑assessment, EU AI Act audit retention. Required for EU deployments.
extensions.x-* map — Vendor‑specific. Unknown x-* keys must NOT fail validation.
✓ required ★ recommended — optional
§ 05 — Try it in sixty seconds

Zero flags. One command. Claude does the rest.

Bare robot-md init scans PCI/USB//dev/tty*, actively probes for Feetech servo buses, matches against the 10-preset library — so-arm101, so-arm101-leader, turtlebot4, picar-x, franka-panda, ur5e, koch-arm, aloha2 (bimanual), unitree-go2 (quadruped), minimal — and emits a validated draft with full DH kinematics + safety defaults already populated. For known robots, ~85 % of the manifest is pre-filled automatically. Follow-ups (register, calibrate, hand-eye) happen inside Claude Code in English — or as flags if you'd rather script them.

▶ Path A — On your machine (terminal)

You're at a shell on the robot (or a laptop with the robot plugged in). Type robot-md init — no flags. Autodetect fills in the rest. Demo at left.

▶ Path B — Inside Claude Code (ask Claude)

You already have Claude Code open. Paste one English sentence; Claude runs the same commands via its Bash tool and wires up MCP for you. Walkthrough →

Path A · terminal · ~/projects/my-bob · zsh
# Zero flags. An interactive setup gets you online fast.
$ pip install robot-md
$ robot-md init

🤖 robot-md v0.6.3 — Let's get your robot online.

? Name your robot: bob
? Scan for hardware? [Y/n] y
  → found Feetech bus (6 servos) + OAK-D camera
  ★ Auto-matched preset: so-arm101

? Register with Robot Registry Foundation (RRF)? [Y/n] y
? Manufacturer / Organization: Acme Corp
  → minting RRN ... RRN-000000000173

? Install MCP server for Claude Code? [Y/n] y
  → installed MCP + using-robot-md skill

? Calibrate arm zero pose now? [Y/n] y
  → move arm to zero and press Enter... ok

▸ Done. bob is online at rcan.dev/r/RRN-000000000173

$ claude
· 6 resources loaded: robot-md://bob/{identity, context, frontmatter...}
› bob is online. `ready` pose auto-calibrated. What should I pick?
> pick up the red lego and place it in the bowl
✓ vision.find(red_lego) → (−62, +25, +522) mm
✓ execute_capability arm.pick(target: red_lego) · approach → descent → grasp → lift · ok
Path B · Claude Code · ~/projects/my-bob
# Inside Claude Code. NLP translates to Bash & MCP automatically.
You: Set up a ROBOT.md for this robot. Use the so-arm101 preset.
     Register it publicly at rcan.dev under manufacturer "acme".
     Then add the robot-md MCP server to this session.

Claude: I'll do this in four steps — install the CLI, init the
        manifest with registration, wire up MCP, then verify.

        [runs: pip install robot-md]
        ✓ robot-md 0.6.3 installed

        [runs: robot-md init my-bob --preset so-arm101 --register...]
        ✓ wrote ROBOT.md  preset: so-arm101
        ✓ my-bob (arm, 6 DoF, 5 capabilities)
        ✓ registered on rcan.dev
          RRN: RRN-000000000042
          Public record: https://rcan.dev/r/RRN-000000000042

        [runs: claude mcp add robot-md -- npx -y robot-md-mcp...]
        ✓ Added stdio MCP server robot-md

        [reads: robot-md://my-bob/frontmatter]
        ✓ MCP server responding — 4 resources live

        Done. Your robot is registered (RRN-000000000042) and I have
        live access to its manifest. Ask me what it can do.

You: What can this robot do?

Claude: my-bob is a 6-DOF SO-ARM101 arm. Five capabilities:
        arm.pick, arm.place, arm.reach, vision.describe,
        status.report. Max payload 0.5 kg. Software E-stop
        at 100 ms. Destructive actions and unknown-surface
        placements gate on human-in-the-loop approval.
01

bob — SO‑ARM101 + OAK‑D

6‑DOF arm + stereo camera, 0.5 kg payload, Opus 4.7 planner, deterministic watchdogs.

→
02

turtlebot4 — wheeled base

Differential drive, ROS 2 driver, nav.* capabilities, SLAM‑gated HITL.

→
03

so‑arm101 — bare arm

A vendor‑canonical ROBOT.md for the SO‑ARM101 kit. Drop in, add brand.

→
04

minimal — zero‑DoF sensor

The smallest valid file. Proves the spec covers the degenerate case.

→
All four live in the repo under examples/. Fork the one closest to your robot and edit.
After init · Every Claude surface recognizes the robot

robot-md init writes both ROBOT.md and CLAUDE.md. From there, three one-command paths to each Claude surface:

Claude Code
claude mcp add robot-md …
Claude Desktop
robot-md install-desktop ROBOT.md
Claude Mobile
paste manifest URL into chat

All three give Claude six live resources + three tools + four slash commands (Mobile gets the resources as a static URL fetch instead of live MCP):

Slash commands
  • /brief-me — operator briefing
  • /check-safety action="…" — gate-check before motion
  • /explain-capability capability="…"
  • /manifest-status — quick health report
Resources
  • robot-md://bob/identity
  • robot-md://bob/context — Claude-ready
  • /frontmatter · /capabilities · /safety · /body

Optional: robot-md install-skill drops the using-robot-md skill into ~/.claude/skills/ — superpowers-aware harnesses auto-invoke the robot-md flow on the operator's first robot-related message.

Custom hardware? (no preset yet)
Three escape hatches:
  • robot-md autodetect --bus feetech:/dev/ttyACM0 — pings every ID on a Feetech servo bus and emits a physics.kinematics[] block with real angle limits + present positions, ready to paste into a draft.
  • robot-md calibrate --hand-eye --marker-pos 300,0,0 ROBOT.md — prints one ArUco marker on paper, places it at a known spot on the table, and solves the OAK-D↔arm-base extrinsic via solvePnP. Writes physics.solver.camera.extrinsic so a planner can project pixel coords into the arm's frame without URDF or external calibration files.
  • robot-md init --wizard — interactive 7-step flow: name, physics type, preset or custom, scan, calibrate zero + sign, optional hand-eye. Resume-safe via a ROBOT.md.init state file.
§ 06 — The rest of the ecosystem

Four standards. Separate roles.

ROBOT.md is designed to configure Claude Code to control a single robot. To ensure safety and verifiable identity, it depends on two independent foundations: RCAN (the signed wire protocol) and the Robot Registry Foundation (permanent identity). OpenCastor (visual agent-harness editor + swarm orchestration) is completely optional.

Declaration · this site
ROBOT.md

What a robot is. A single file, YAML + markdown. Designed for Claude's agent harnesses (Code / Desktop / Mobile) but readable by any planner.

github.com/RobotRegistryFoundation/robot-md →
v0.2 design draft — signing + registry ingestion →
Wire protocol · rcan.dev
RCAN 3.0+

What a robot speaks. Signed envelopes, LoA enforcement, ml-dsa-65 primary crypto, EU AI Act compliance blocks (§23–§27). Open, Apache‑2.0, community‑governed.

rcan.dev →
Registry · robotregistryfoundation.org
Robot Registry Foundation

Where a robot lives. Permanent, globally‑unique RRNs. Resolvable rrn:// URIs. Neutral foundation; Cloudflare Pages + Workers + D1.

robotregistryfoundation.org →
Agent harness · opencastor.com
OpenCastor

Optional. Visual editor for Claude agent harnesses plus multi-robot swarm orchestration. Compose MCP stacks, wire tools, scale from one robot to a fleet. ROBOT.md is its native robot format — but Claude Code reads the same file standalone. Pick it up when you outgrow a single terminal.

github.com/craigm26/OpenCastor →