opencastor

OpenCastor

Productized open-core RCAN runtime — gateway-as-kernel, drivers, fleet, cloud bridge, UI. The most fully-documented RCAN runtime; not the only one.

Peer runtime: opencastor and robot-md are first-class peer RCAN 3.x runtimes against a single ROBOT.md — see PEER_RUNTIMES.md for the side-by-side.

94,438 lines of Python · 7,334 tests · Python 3.10–3.13

What is OpenCastor

OpenCastor is an open-source runtime for embodied AI. It implements the RCAN open protocol and handles the hard parts: safety gates, multi-provider AI routing, hardware drivers, messaging channels, and fleet management.

Point it at any LLM (Gemini, GPT-4.1, Claude, Ollama, and 13 more) and any robot body (Raspberry Pi, Jetson, Arduino, ESP32, LEGO) via a single YAML config. Your robot answers to WhatsApp, Telegram, Discord, Slack, and Home Assistant — and learns from its own experience through the Sisyphus self-improvement loop.

RCAN ≠ OpenCastor. RCAN is an independent open protocol — like DNS and ICANN, but for robotics. Any robot can implement RCAN without using OpenCastor. OpenCastor is one implementation that helped inform the spec.

Quick Start

1. Install

pip install "opencastor>=3.1"

The >=3.1 is load-bearing, not decoration. A bare pip install opencastor resolves the old CalVer line (2026.4.23.0), because under PEP 440 a date sorts above 3.x — and that wheel has no castor up in it. Every install instruction in this repository uses this exact string. See docs/setup/pairing.md.

2. Bring the robot up

castor up            # one command: scans the bus, writes the units, prints a pairing QR

castor up is the path the OpenCastor iOS app and the flashable Pi image both use. It detects what is on the I²C bus, picks an archetype, writes four systemd user units, and prints a QR to scan. It starts on simulated wheels by design — turning on real PWM is a deliberate later edit in gateway-policy.env.

Prefer the long-form wizard, or have no robot to detect yet?

castor setup                 # 4-step wizard, writes an rcan.yaml
castor init --shape rc-car   # just a ROBOT.md, shaped like a car

castor init asks what shape the robot is before anything else — arm, rc-car or sim — because every default it used to offer described an arm. The rc-car manifest points at castor up, which is the only bring-up program that knows that shape.

The wizard will:

Name your robot and assign an RRN (Robot Registration Number)
Generate a config file at ~/.config/opencastor/<name>.rcan.yaml
Show a QR code to connect to the Fleet UI at app.opencastor.com
Configure your AI brain provider (Gemini, Claude, OpenAI, or local Ollama)

Have a Pollen Microduck? Skip the wizard — one command does everything:
castor duck
It finds the duck on your network, checks SSH and robot group access (printing the exact fix if either is missing), asks robotd for live health, and writes the config. Then castor duck test makes it walk.

3. Start your robot

# Start the AI brain + REST API (port 8000 standalone; 8081 under `castor up`)
castor gateway --config ~/.config/opencastor/bob.rcan.yaml

# Start the cloud bridge (connects robot to Fleet UI — outbound-only)
castor bridge --config ~/.config/opencastor/bob.rcan.yaml

Ports — the one table

Every port below comes from castor/up.py: three adjacent services at --base-port (default 8080), plus one fixed helper. Nothing else in this repository should quote a different number for a castor up robot.

Service	systemd user unit	Port	Answers
Gateway (`robot-md-gateway`)	`<name>-gateway.service`	8080 (`base + 0`)	`/v1/invoke` with signed receipts — the port in the pairing QR
Runtime (OpenCastor)	`<name>-castor.service`	8081 (`base + 1`)	`/health`, `/api/stop`, `/ws/telemetry`
Console	`<name>-console.service`	8082 (`base + 2`)	chat brains, `/surface`, `/gaps`
RRF key-resolver stub	`<name>-rrf-stub.service`	8090 (fixed)	loopback `kid` lookup

castor up --base-port 8110 moves the first three to 8110/8111/8112; the RRF stub does not move, so a second robot on one host needs the stub's port adjusted by hand. Standalone castor gateway (no castor up) still defaults to 8000 — that is a different program on a different port, not this table.

4. One-command systemd setup

castor bridge setup   # generates and optionally installs systemd services

Docker

docker run -it \
  -v ~/.config/opencastor:/config \
  -e OPENCASTOR_CONFIG=/config/bob.rcan.yaml \
  ghcr.io/craigm26/opencastor:2026.4.1.0 \
  castor gateway

Profile	Description	Requires
`apple_native`	Mac with Apple Silicon (M1–M4) — runs models on-device via Apple Foundation Models. No API key needed.	macOS, Apple Silicon
`mlx_local_vision`	Mac with Apple Silicon — open-source models via MLX (Llama, Mistral, Qwen). More model choice than apple_native.	macOS, Apple Silicon
`ollama_universal_local`	Any machine — runs local models via Ollama. Works on Mac, Linux, and Windows.	Ollama installed

On Apple Silicon, apple_native is the default. The wizard will ask which Apple model profile fits your use case:

Apple Profile	Use case	Guardrails
`apple-balanced` ⭐	General chat and robot commands — best starting point	Default
`apple-creative`	Creative tasks, less restrictive output	Permissive Content Transformations
`apple-tagging`	Classifying or labeling objects/scenes	Default

Features

Protocol 66 safety — ESTOP never blocked, local safety always wins, confidence gates run on-device
RCAN protocol — hybrid signing (ML-DSA-65 + Ed25519), mandatory LoA, canonical JSON wire format, §22-26 compliance builders, BLE/LoRa/MQTT carriers
Multi-provider AI — Gemini, Claude, OpenAI, Ollama, MLX (Apple Silicon), Groq, DeepSeek, and 7 more; hot-swap via YAML
Fleet UI — real-time fleet dashboard at app.opencastor.com; no port forwarding needed
SO-ARM101 arm support — auto-detected via USB, guided setup for follower/leader/bimanual configurations
18 hardware presets — Raspberry Pi, Jetson, Arduino, ESP32, LEGO Mindstorms, OAK-D, LeRobot SO-ARM101, and more
Self-improving loop — Sisyphus PM→Dev→QA→Apply pipeline learns from every episode
Messaging channels — WhatsApp, Telegram, Discord, Slack, Home Assistant, MQTT
castor setup wizard — guided onboarding with QR codes; works headless on Pi

Architecture

[ app.opencastor.com / Fleet UI ]
          │  Firebase / Firestore
          │
   [ Cloud Functions ]            R2RAM enforcement + rate limiting
          │
   [ castor bridge ]              outbound-only Firestore connection
          │
   [ castor gateway ]             FastAPI REST + messaging channels
          │
   ┌──────────────────────┐
   │   Protocol 66 Safety │       ESTOP | confidence gates | bounds
   └──────────────────────┘
          │
   [ Tiered Brain ]               Gemini / Claude / GPT / Ollama / …
          │
   [ RCAN Config + Drivers ]      .rcan.yaml → hardware abstraction
          │
   [ Robot Hardware ]             Pi / Jetson / Arduino / SO-ARM101 / …

RCAN Protocol Features

Replay prevention — hybrid signatures (ML-DSA-65 + Ed25519) over canonical JSON bodies
Level of Assurance (LoA) — mandatory in the RCAN protocol; gates control-plane operations behind HiTL authorization
Canonical JSON wire format — rcan.canonical_json(body) produces byte-identical serialization across Python and TypeScript SDKs
§22-26 compliance artifacts — emit §23 safety benchmarks, §24 IFU, §25 post-market incident reports, §26 EU register entries via rcan.build_* builders
Federation + constrained transport — BLE / LoRa / MQTT carriers; RRN-based identity resolution via rcan.dev
Post-quantum ready — NIST FIPS 204 ML-DSA-65 is the primary signing scheme (Q-Day 2029 is NOW)

castor CLI Reference

Command	Description
`castor setup`	Interactive onboarding wizard — config, RRN, Fleet UI QR code
`castor gateway`	Start AI brain + REST API + messaging channels
`castor bridge`	Start cloud bridge (Fleet UI connection)
`castor scan`	Auto-detect connected hardware (USB, I2C, V4L2)
`castor doctor`	System health check — providers, channels, hardware
`castor fix`	Auto-fix common configuration issues
`castor status`	Provider and channel readiness summary
`castor improve`	Run Sisyphus self-improvement on recent episodes
`castor audit --verify`	Verify audit chain integrity
`castor approvals`	Review and approve pending high-risk commands
`castor deploy`	Push config to a remote robot over SSH
`castor fleet`	Discover and monitor all robots on the local network
`castor upgrade`	Pull latest version + pip install + service restart

Full reference: docs.opencastor.com/runtime/cli

Configuration

Minimal bob.rcan.yaml:

rcan_version: "3.0"
metadata:
  robot_name: bob
agent:
  provider: google
  model: gemini-2.5-flash
drivers:
  - id: wheels
    protocol: pca9685
channels: {}

That's it. castor gateway --config bob.rcan.yaml starts the REST API, messaging channels, and the self-improving loop.

Swap the AI brain with one line:

agent:
  provider: anthropic
  model: claude-sonnet-4-6

Protocol 66

Protocol 66 is RCAN's mandatory safety layer. Current OpenCastor conformance: 94%.

Key invariants:

ESTOP delivered at QoS 2 (EXACTLY_ONCE) — never blocked by backpressure
Local safety always wins — cloud commands pass through the same confidence gates as local commands
Audit chain required for all flagged commands
GuardianAgent has veto authority over unsafe actions

P66 manifest: sbom/ · Full spec: rcan.dev/docs/safety/

Fleet UI

app.opencastor.com — sign in with Google to see your fleet.

Real-time status cards for all registered robots
Robot detail: telemetry, command history, chat-scope instructions
ESTOP button on every screen
Consent management — approve/deny R2RAM access requests
Revocation display — shows if a robot's identity has been revoked
LoA display — shows operator Level of Assurance on control commands

Robots connect via castor bridge (outbound-only Firestore). No open ports on the robot side.

SO-ARM101 Arm Support

The LeRobot SO-ARM101 6-DOF serial bus servo arm is auto-detected via USB VID/PID (CH340, 0x1A86/0x7523).

pip install "opencastor[lerobot]>=3.1"
castor scan                          # detects arm + suggests preset
castor wizard --preset so_arm101     # guided config: follower / leader / bimanual
castor gateway --config so_arm101.rcan.yaml

castor scan counts connected Feetech boards and automatically suggests the right preset: single arm (follower or leader), or bimanual pair (ALOHA-style). Koch arms use the same detection path.

Where OpenCastor sits

OpenCastor is Layer 4 of the OpenCastor stack — the productized robot-facing runtime. It depends on:

robot-md-gateway — Layer 3, the open safety kernel. Same code in commercial and community deployments.
continuonai/rcan-spec — Layer 5, the wire protocol.
Robot Registry Foundation — Layer 6, the neutral registry.

The safety story is identical at every tier — hobbyist running gateway directly, or enterprise running OpenCastor full. What you pay for is operational ergonomics, fleet scale, compliance prep, and support.

OpenCastor is a productized open-core RCAN runtime — gateway-as-kernel plus drivers, fleet management, cloud bridge, and commercial support. RCAN-the-protocol is implementation-independent; OpenCastor is the most fully-documented runtime that speaks it.

Everything else in the ecosystem is independent; adopt one, or all seven.

Layer	Piece	What it is
Declaration	ROBOT.md	The file a robot ships at its root. YAML frontmatter + markdown prose. Declares identity, capabilities, safety gates. Spec + Python CLI.
Agent bridge	robot-md-mcp	MCP server that exposes a `ROBOT.md` to Claude Code, Claude Desktop, Cursor, Zed, Gemini CLI — any MCP-aware agent.
Wire protocol	RCAN	How robots, gateways, and planners talk. Signed envelopes, LoA enforcement, PQC crypto. Think HTTP for robots.
Python SDK	rcan-py	`pip install rcan` — `RCANMessage`, `RobotURI`, `ConfidenceGate`, `HiTLGate`, `AuditChain`.
TypeScript SDK	rcan-ts	`npm install rcan-ts` — same API surface for Node + browser.
Registry	Robot Registry Foundation	Permanent RRN identities. Public resolver at `/r/<rrn>`. Like ICANN for robots.
Productized runtime ← this	OpenCastor	This repo. Productized open-core RCAN runtime — connects LLM brains to hardware bodies. Safety gates, multi-provider AI routing, 18+ hardware drivers, messaging channels, fleet management.

See also: the ROBOT.md quickstart — one command puts a Bob-class robot in Claude Code via the MCP bridge.

Ecosystem (versions)

Project	Version
OpenCastor (this)	v2026.4.17.0
Fleet UI	live
RCAN Protocol	live matrix
rcan-py	v2.0.0
rcan-ts	v2.0.0
ROBOT.md	v0.2.0 (schema v1.1)
robot-md-mcp	v0.1.3
Robot Registry Foundation	v3.0

Contributing

OpenCastor is Apache 2.0 and community-driven.

Discord: discord.gg/jMjA8B26Bq
Issues: github.com/craigm26/OpenCastor/issues
PRs: See CONTRIBUTING.md
Docs: docs/claude/ — structure, API reference, env vars

Conformance is not certification.

Conformance to RCAN tracks (L1–L4 protocol, Gateway Authority, HIL Runtime Safety) is self-asserted via signed bundles and independently replayable from those bundles. Conformance is not certification. Certification requires audit by a qualified third-party body, which is intentionally out-of-scope for the foundation in 2026.

Where safety is actually enforced.

Physical safety is enforced at Layer 3 (robot-md-gateway) or Layer 4 (a runtime that embeds it, e.g., OpenCastor). Declaration alone (Layer 1) does not enforce safety. Agent host alone (Layer 2) is not the safety boundary. If a deployment lacks Layer 3, no safety claim attaches to it.

License

Apache 2.0 · by Craig Merry

Implements the RCAN open protocol. RCAN is an independent open standard — any robot or runtime can implement it.

core rc-car rpi elevenlabs sdk whatsapp whatsapp-twilio telegram discord slack mqtt channels rcan dynamixel hlabs lerobot reachy cloud setup esp32 ev3 spike stem-hardware vertex homeassistant webrtc microduck-webrtc ros2 onnx onnx-gpu gestures apple simulation paintbench paintbench-agent all dev

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

opencastor-1!3.4.0.tar.gz (2.8 MB view details)

Uploaded Sep 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

opencastor-1!3.4.0-py3-none-any.whl (2.3 MB view details)

Uploaded Sep 10, 2026 Python 3

File details

Details for the file opencastor-1!3.4.0.tar.gz.

File metadata

Download URL: opencastor-1!3.4.0.tar.gz
Upload date: Sep 10, 2026
Size: 2.8 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for opencastor-1!3.4.0.tar.gz
Algorithm	Hash digest
SHA256	`cfb3f99a2c6dd1227a0293b33e2c1f128bd91870220b71bfaeb6df5c88237283`
MD5	`0d0c39e478f4cec66247f4899fff4a74`
BLAKE2b-256	`d8b5ce33b1e8d52a6d709c4f6c4bbff56e014bb25577cdd0665869f81dbcb43e`

See more details on using hashes here.

File details

Details for the file opencastor-1!3.4.0-py3-none-any.whl.

File metadata

Download URL: opencastor-1!3.4.0-py3-none-any.whl
Upload date: Sep 10, 2026
Size: 2.3 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.5

File hashes

Hashes for opencastor-1!3.4.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`fe6103b85a7b4dba7551d4a01719f7c3a6efc18e052720d63df33dcf0cab5382`
MD5	`f7f57eed7c2e0ca561d7a1aa82769d85`
BLAKE2b-256	`655034475d1b53ded34338e12629918ee48ae94fdd2b95e15fef9d3b6d984fc7`