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.

RCAN 3.0 wire protocol, native RRF registry-compatible JSON Schema draft 2020‑12 Designed for Claude Code · Desktop · Mobile
§ 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 it speaks. The Registry is where it lives. The runtime is what it runs. Adopt any one without the others — or all four together and get a fleet.

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.
CryptoPQC‑hybrid‑v1 at L2+. ML‑DSA‑65. Ed25519 accepted at L1 only, sunset mid‑cycle.
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. Resolvable via rrn:// URIs.
NeutralA foundation, not a vendor. Cloudflare Pages + Workers + D1. No seat fees, no per‑robot tax.
PublicPublic endpoint at robotregistryfoundation.org/r/<rrn>. Self‑hosted mode supported.
Layer 1 · RuntimeOpenCastor + any compatible runtime
ReferenceOpenCastor — open‑source agent editor and robotics runtime. 7,800+ tests, Claude Opus 4.7 as planner, OpenVLA‑7B reactive.
PortableROS 2, Spot SDK, HuggingFace LeRobot, Pollen Reachy — any of them can ship a ROBOT.md.
Bring‑your‑ownThe spec depends on no runtime. Export a ROBOT.md from your existing stack in an afternoon.
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 robotregistryfoundation.org/r/<rrn> — returns the robot's ROBOT.md, its compliance block, its registry metadata.
  • 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

If a robot can describe itself in one file, every tool in the agentic stack — planner, validator, registry, gateway — can meet it halfway.

§ 03 — Claude, three surfaces

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.

● Shipping v0.1

Claude Code

SessionStart hook → robot-md context → session context

A drop‑in hook at ~/.claude/hooks/robot-md.sh. Reads ./ROBOT.md from cwd and injects the context block — same mechanism that orients Claude around a codebase via CLAUDE.md today.

pip install robot-md → claude ./
◑ Shipping v0.2

Claude Desktop

MCP server robot-md-mcp — resources + tools

Exposes frontmatter, capabilities, and safety as MCP resources. Tools: validate, render, query_status, invoke_skill. The invoke tool bridges to the gateway via RCAN, respecting every HITL gate declared in the file.

Recommended MCP · listed like filesystem, github
◑ Shipping v0.2

Claude Mobile · iOS

URL fetch → robotmd.dev/r/<rrn>

Operators host their ROBOT.md at a stable URL (or via the Registry). Claude on a phone fetches it, reasons about what the robot can do, and dispatches commands through the copy‑paste or invoke‑bridge pattern. No new SDK needed on Anthropic's side.

Works today. No Anthropic change required.
§ 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✓Protocol version — "3.0" recommended. 2.1+ accepted; 1.x rejected for EU AI Act gap.
metadata.robot_namestring✓Short display name. Must match the body H1. Used in every planner citation.
metadata.rrnstring★Robot Registry Foundation identifier. Empty string allowed until registered.
physics.typeenum✓arm · wheeled · tracked · legged · arm+camera · humanoid · other
physics.dofint✓Degrees of freedom. 0 permitted for purely sensory nodes.
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.
networkmap★RRF endpoint, gateway port, signing algorithm, transports. Required for network‑addressable robots.
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

Install, validate, render, hand it to Claude.

The reference CLI is a small Python package. It validates against the schema, renders the machine‑readable block, and emits a context block ready for a Claude Code SessionStart hook.

~/projects/bob · zsh
$ pip install robot-md
Successfully installed robot-md-0.1.0

$ robot-md validate bob.ROBOT.md
✓ bob (arm+camera, 6 DoF, 5 capabilities)
✓ rcan_version 3.0  ·  schema v1 OK
✓ body sections present

$ robot-md render bob.ROBOT.md | head -5
rcan_version: "3.0"
metadata:
  robot_name: bob
  rrn: RRN-000000000001
  manufacturer: craigm26

$ robot-md context bob.ROBOT.md \
    > ~/.claude/sessions/robot-context.md
# now Claude Code loads it on every session.

$ claude .
· loaded CLAUDE.md
· loaded ROBOT.md → bob
→ hi. bob is online. ask me to pick something.
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.
§ 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 when v0.2 ships. 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.

The full proposal — integration surface, timing, evidence, commitments — lives at proposal/anthropic-adoption-proposal.md in the repo. 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/continuonai/robot-md →
Wire protocol · rcan.dev
RCAN 3.0

What a robot speaks. Signed envelopes, LoA enforcement, PQC‑hybrid 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 →
Runtime · opencastor.com
OpenCastor

What a robot runs. An open‑source agent editor and robotics runtime: community contributions, 7,800+ tests, Claude Opus 4.7 as the reference planner. Not required.

github.com/craigm26/OpenCastor →