GitHub - emergingrobotics/gorai: Go-based Robotics Framework built around NATS.io

The robotics platform for the AI era. Pronounced "go-ray" (like "sting-ray") Why Gorai? A robot is a distributed system — so build it like one. Even a "single" robot is already a network of MCUs, SBCs, sensors, and sometimes a base station. Gorai stops pretending otherwise: every sensor and actuator is a service on a NATS mesh — discovered at runtime, addressed by name, never wired by hand. The discipline that built reliable cloud systems — service discovery, location transparency, health checks, fan-out, replay — is exactly what a real robot needs. Capabilities, not wiring. Sensors are resources you read; actuators are tools you call. Any agent on the mesh can perceive the world and change it — the capability model MCP gives AI agents, delivered natively over NATS with no MCP server in the path. We call it NCP, the NATS Capability Protocol. One robot can be many machines. Because capabilities are addressed by name and not by location, a single logical robot can span a rover, a drone, a sensor mast, and a compute box — composed at runtime, degrading gracefully as platforms join and leave. This is the Composite Robot, and it's the whole point. Autonomy without replay is folklore. Action logs, state streams, and replay are first-class platform concerns — not add-ons. AI execution is welcome but never trusted: safety is enforced at the capability node, not the agent. Agent-compatible, not agent-dependent — deterministic state machines and rule-based planners drive the same capabilities. Build robots like software. Run them like systems. Opinionated, pragmatic, operational. If you already think in APIs, distributed systems, and deployments, you'll be productive in days, not months. Read the north star: VISION.md. Full documentation lives at gorai-docs. Strategy, architecture, specifications, hardware analysis, a 20-chapter book, and implementation guides — all indexed for both humans and AI agents. Point your AI agent at that repo and it will navigate 100+ documents via CLAUDE.md and INDEX.md automatically. What gorai Is (and Isn't) There are two different binaries in a Gorai project, and it's important not to confuse them: Your robot binary — the program that runs on the Pi and does the robot stuff. This is your own Go module: a main.go that blank-imports the components you want and calls gorai.Run(). Its embedded NATS server, the mesh, and every component compile into this one static binary. It is fully self-contained and needs nothing from the gorai tool at runtime — you copy it to the robot and run it. The gorai CLI — a developer and operator tool you run at your workstation. It never runs on the robot in production. Think of it as kubectl + a build wrapper + a package helper, rolled into one command. So yes — you could just go build . your robot project and scp the result to the Pi. The gorai CLI earns its place by doing the things around that binary that a plain go build does not: What you want to do gorai command What it actually does Catch config errors before deploying gorai validate robot.json Validates your RDL (schema, deprecations) so you don't ship a broken config to the field Iterate fast without cross-compiling gorai run robot.json Runs the same runtime your robot binary uses, in the foreground — skips the compile-and-copy loop Produce a deployable binary gorai build robot.json --target linux/arm64 Wraps go build with validation, cross-compile ergonomics, version stamping, and deploy hints Find and add components gorai component search/add Wraps go get and edits the blank-import list in main.go (the Caddy model — see below) See what's running on a live mesh gorai mesh services / watch / schemas Connects to a running NATS mesh and introspects it — your service-discovery browser for a robot or fleet in the field The first three are conveniences over the Go toolchain. The mesh commands are the part you genuinely cannot replicate with go build — they observe and debug a running system, which is what you reach for once a robot (or several) is live. The rest of this README covers how to install the CLI, define a robot, and build it.