Spec v1 · draft 0.1 · live
part of the OpenCastor ecosystem
VOL. 1 · NO. 1
An open declaration format for agentic robots
APRIL 17, 2026 · OPENCASTOR ECOSYSTEM

ROBOT.md

One file at the root of your robot. YAML frontmatter a schema can trust, markdown prose a planner can read. The CLAUDE.md of physical machines — so the same agent that ships your code can safely drive your arm, your rover, your humanoid.

▶ On your machine (terminal)
$ pip install robot-md && robot-md init my-bob --preset so-arm101 --register
One line. Scans hardware, writes ROBOT.md, mints an RRN at rcan.dev, prints the claude mcp add line.
▶ Inside Claude Code (ask Claude)
"Set up a ROBOT.md for this robot. Use the so-arm101 preset. Register under manufacturer acme, email me@acme.com. Then add the robot-md MCP server."
Paste that sentence. Claude uses its Bash tool to run the one-liner, wires up MCP, and verifies. Full walkthrough →
Claude Code · Desktop · Mobile all three, one install path each RCAN 3.0+ wire protocol, native RRF registry · rcan.dev Any MCP-aware agent Cursor · Zed · Gemini CLI · Codex
§ 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-000000000001
  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 }
  reactive:  { provider: local,     model: openvla-7b     }
---

# bob

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

## 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. Each independent. Each composable.

ROBOT.md declares what the robot is. RCAN is how fleets speak. The Registry is where robots live. The runtime is whatever executes — and for Tier 0, that's Claude Code itself. Adopt one layer or all four.

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‑17. 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 production.
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 2Production: OpenCastor adds a reactive VLA layer, P66 hardware interlocks, fleet scale, EU AI Act audit. Opt‑in when you need it.
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.

  • 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.

  • 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, writes the assigned RRN back into the file, saves the issued API key at ~/.robot-md/keys/<rrn>.apikey (mode 600).
  • 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 — from a developer's terminal, from a desktop chat, from a phone in the field. Planner‑agnostic by design: the same file, the same MCP server, works with Claude Code, Claude Desktop, OpenAI Codex CLI, Google Gemini CLI, Cursor, Zed, Cline, Continue.dev — anything that speaks MCP.

● Shipping

Claude Code · CLI

Zero-touch. robot-md init prints the claude mcp add line for you.

Built for operators at a terminal. pip install robot-md && robot-md init my-bob --preset so-arm101 --register scans hardware, writes ROBOT.md, mints an RRN, generates CLAUDE.md, and prints the claude mcp add one-liner. Paste it, open Claude Code, and the planner reads your robot's frontmatter, capabilities, safety gates, and prose body as MCP resources. From there Claude's Bash tool talks directly to your robot over serial, HTTP, MQTT.

One terminal. Two commands. 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_versionstring✓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_namestring✓Short display name. Must match the body H1. Used in every planner citation.
metadata.rrnstring★RRF-assigned identifier (e.g. RRN-000000000001). Empty until robot-md register mints one. Resolves via rcan.dev/r/<rrn>.
metadata.rrn_uristring—Optional URI form: rrn://<org>/<category>/<model>/<id> — dereferenceable by any RCAN-aware client.
physics.typeenum✓arm · wheeled · tracked · legged · arm+camera · humanoid · sensor · other
physics.dofint✓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.solvermap—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.estopmap✓At minimum: software: true + response_ms. Hardware button recommended for Annex III systems.
safety.hitl_gatesarray★Scopes (destructive, system, …) that require human authorization via RCAN §8 AUTHORIZE.
brainmap★Planner + reactive model declaration. Task‑routing overrides. Required if the robot uses an LLM in the loop.
network.rrf_endpointstring★RRF resolver — defaults to https://robotregistryfoundation.org. Serves the signed manifest at /r/<rrn> and FRIA at /api/v1/robots/<rrn>/fria.
network.signing_algstring★RCAN 3.0 primary: ml-dsa-65 (PQC). ed25519 accepted at Level-of-Assurance 1 only; sunset mid-3.x.
compliancemap★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

One command. Preset-matched. Claude knows your robot.

robot-md init is the super-duper-quick path: scans PCI/USB//dev/tty*, 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. For custom builds, --wizard walks you through the rest in 7 steps.

▶ Path A — On your machine (terminal)

You're at a shell on the robot (or a laptop with the robot plugged in). Run the one-liner below in the terminal. The full demo is shown 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
# The whole thing — one command, zero OpenCastor, zero config files:
$ pip install robot-md && \
      robot-md init my-bob --preset so-arm101 --register \
        --manufacturer acme --contact-email me@acme.com

✓ wrote ROBOT.md  preset: so-arm101
✓ my-bob (arm, 6 DoF, 5 capabilities)
✓ registered on RRF
  RRN: RRN-000000000042
  RCAN URI: rcan://rcan.dev/acme/so-arm101/1-0/my-bob
  API key saved to ~/.robot-md/keys/RRN-000000000042.apikey (mode 600)
  Public resolver: https://rcan.dev/r/RRN-000000000042
✓ wrote CLAUDE.md                     # agent reads it at session start

Next — hand your manifest to Claude Code:
  claude mcp add robot-md -- npx -y robot-md-mcp "$(pwd)/ROBOT.md"

# Or wire Claude Desktop in one shot (macOS/Windows):
$ robot-md install-desktop ROBOT.md
✓ added `robot-md` entry to ~/Library/…/claude_desktop_config.json

# Optional: drop the superpowers skill so any skill-aware harness
# auto-invokes robot-md on the operator's first robot-related message.
$ robot-md install-skill
✓ installed ~/.claude/skills/using-robot-md/SKILL.md

# (Optional) Physical calibration — only if your robot has an arm:
$ robot-md calibrate --zero ROBOT.md
$ robot-md calibrate --hand-eye --marker-pos 300,0,0 ROBOT.md

$ claude
· 6 resources loaded: robot-md://my-bob/{identity, context, frontmatter,
                                           capabilities, safety, body}
· 3 tools: validate, render, doctor_summary
· 4 slash commands: /brief-me  /check-safety  /explain-capability  /manifest-status
→ Claude knows your robot. Ship.
01

bob — SO‑ARM101 + OAK‑D

6‑DOF arm + stereo camera, 0.5 kg payload, Opus 4.7 planner, OpenVLA reactive.

→
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 — An open letter

A proposal — not a pitch — for Anthropic.

ROBOT.md is drafted for review so readers can inspect the full context. The ask is narrow. The adoption cost is small. The cost of silence is structural.

Draft v0.1open for review

To: Product · DevRel · Applied, Anthropic From: craigm26 · OpenCastor maintainer

The best planner on the market for physical robots is already yours. The reference arm we run — a 6‑DOF SO‑ARM101 we call bob — routes its reasoning through Claude Opus 4.7 with a local VLA model for sub‑second reflexes. It works. Dozens of community robots now do the same.

The physical‑AI market in 2026 is in flight, and configuration‑format lock‑in determines which planner adopters default to. CLAUDE.md won the developer's root directory. ROBOT.md is the same move, one layer out — the file a robot ships at its root so any agent can pick it up and be useful in the first second of the first session.

What we're asking for is small. Endorse the pattern in Claude Code docs the way CLAUDE.md is endorsed. List robot-md-mcp beside filesystem and github in your recommended MCPs — it's shipped (npm, v0.2.1+) with server instructions, 6 resources, 3 tools, and 4 slash commands that route to the robot's manifest by description-match alone. Document the URL‑fetch pattern on Claude Mobile — the phones already do the work. If the repo should live at Anthropic/robot-md, we will transfer it; committer status retained, governance open.

Not asked: code contributions, exclusivity, or IP up‑front. ROBOT.md is designed to work best with the provider's agent harnesses — Claude Code, Desktop, Mobile — but other planners (GPT, Gemini) are welcome to read the file too. We would simply prefer the operator's default, on day one, to be the planner that already drives our robot.

Feedback via GitHub issues. Coffee via email.

— craigm26 · craigm26@gmail.com · April 17, 2026
§ 07 — The rest of the ecosystem

The OpenCastor ecosystem, at a glance.

ROBOT.md sits alongside three sibling projects. Each is independent; together they give a robot an identity, a voice, a registry, and a runtime. All four can be adopted à la carte.

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 →
Production runtime · opencastor.com
OpenCastor

Optional — for fleets, regulated deployments, and real-time reactive control. Open‑source, community‑driven, 7,800+ tests, Claude Opus 4.7 as reference planner, OpenVLA‑7B reactive. Single‑robot setups don't need it — Claude Code alone is Tier 0.

github.com/craigm26/OpenCastor →