Gorai – a go-based robotics framework for the AI era Gorai, a Go-based robotics framework, treats robots as distributed systems by using a NATS mesh for service discovery and communication, enabling sensors and actuators to be addressed by name rather than wired connections. The framework supports composite robots spanning multiple machines, enforces safety at capability nodes, and provides a CLI for validation, building, and mesh introspection. The robotics platform for the AI era. Pronounced "go-ray" like "sting-ray" 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 areresourcesyou read; actuators aretoolsyou call. Any agent on the mesh can perceive the world and change it — the capability model MCP gives AI agents, delivered natively over NATS withno 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 theComposite 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 atStrategy, 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 gorai-docs . CLAUDE.md and INDEX.md automatically. 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 — you copy it to the robot and run it. gorai tool at runtime - The — a gorai CLI 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. Build a robot in under an hour. Write JSON, get a binary, deploy to a Linux host Raspberry Pi/Orange Pi/etc . 1. Install the CLI a dev/operator tool — not the robot itself go install github.com/emergingrobotics/gorai/cmd/gorai@latest 2. Create a robot project from the template git clone https://github.com/emergingrobotics/gorai-robot-template.git my-robot cd my-robot 3. Edit robot.json, then validate and run gorai validate robot.json gorai run robot.json 4. Build for deployment gorai build robot.json -o robot --target linux/arm64 scp robot pi@raspberrypi:~ && ssh pi@raspberrypi ./robot No containers. No K8s. No external services — just a single binary on a Raspberry Pi 5 or Orange Pi 5. That's the simple case, not the ceiling: point several binaries at a shared NATS bus or a leaf node and the mesh ties multiple platforms into one logical robot — same code, no rewrite. Gorai targets prosumer-accessible field robots across marine, surface, underwater, and land domains — autonomous submersibles, autonomous surface vessels, and land robots. An autonomous submersible, for example, runs gorai run on a Linux host Raspberry Pi/Orange Pi/etc inside a pressure housing. Gorai uses the Caddy model for component packaging: your robot project is a standard Go module, and the import list in main.go is the component manifest. Each component self-registers via init calling registry.RegisterComponent . There is no custom package manager -- Go modules handles everything. A robot's main.go declares which components to include via blank imports: package main import gorai "github.com/emergingrobotics/gorai/pkg/gorai" // Remote proxy components from GoRAI core "github.com/emergingrobotics/gorai/components/motor/remote" "github.com/emergingrobotics/gorai/components/camera/remote" // Third-party component from the ecosystem "github.com/someone/gorai-component-lidar/rplidar" // Custom component in this repo "my-robot/components/ballast" func main { gorai.Run } The Go import list replaces package.json , requirements.txt , or any custom manifest. What you import is what gets compiled into the binary. gorai component search lidar Find components in the ecosystem gorai component add sensor/rplidar go get + add blank import to main.go gorai build robot.json Single binary with everything included Custom components are ordinary Go packages in your project's repo. Write a package with an init function that calls registry.RegisterComponent , add a blank import in main.go , and it compiles into the binary alongside everything else. Sharing a component means publishing a Go module. Extract the package into its own repo, push to GitHub, and anyone can gorai component add it. No registry servers, no package approval process -- standard Go module hosting. This is a key advantage of choosing Go as the platform language. The single-binary story extends all the way to the component ecosystem: no runtime dependency resolution, no DLL hell, no version conflicts at deploy time. Every dependency is resolved at build time by the Go toolchain, and the result is one static binary you copy to the robot. Non-Go components Python vision pipelines, C++ SLAM run as external services communicating via NATS. They do not compile into the binary. This is Phase 2 complexity. For the full design, see docs/package-dev-approach.md /emergingrobotics/gorai/blob/main/docs/package-dev-approach.md . Use Gorai if you: - Want real autonomy not educational toys, not simulations - Need approachable software productive in days, not months - Value modern tooling AI-assisted coding, simple deployment - Are building prosumer robots marine monitoring, land vehicles, research platforms - Are a software-first team adding physical embodiment to AI/ML or scaling from one robot to fleets - Care more about behavior, coordination, and operations than low-level kinematics or middleware internals Use ROS 2 if you: - Work in enterprise/research robotics warehouse automation, autonomous vehicles - Need the full ROS ecosystem thousands of packages, simulation, SLAM libraries - Are in academia where ROS 2 is the standard - Need deep hardware or control-architecture experimentation ROS 2 is the right platform We're not replacing ROS 2 — we're targeting a different market. Think "ROS 2 for prosumers," with an AI-first design for the next wave of autonomous systems. Robotics is shifting because decision-making is moving up the stack : autonomy is no longer only hand-authored logic. Perception, planning, and task selection are increasingly learned, probabilistic, or agentic. That shift— physical AI —changes what a platform must provide. What the future market is: Physical AI — systems where behavior, autonomy, and coordination are more complex than motor control or kinematics Software-first teams — engineers and AI/ML practitioners who need to ship robots and fleets without becoming robotics-infrastructure experts Autonomy as a spectrum — from scripted behaviors and state machines to learned perception and agentic planners, all needing the same operational surface Why Gorai is built for it: AI-first by design — we treat AI-driven execution as a first-class assumption: capability surfaces for tools, governance and safety at runtime, and auditability/replay as baseline, not add-ons Start simple, scale without rewriting — one binary today; same contracts and RDL when you add ML services, multi-robot coordination, or fleet operations Clarity over maximal flexibility — we optimize for teams whose hardest problems are autonomy, orchestration, deployment, and safety—not low-level robotics research We are not trying to serve every robot. We are building the default platform for teams that ask: "How do we safely decide what the robot should do next—and scale that across systems?" For the full strategic context, see Gorai Overarching Strategy https://github.com/emergingrobotics/gorai-docs/tree/main/docs/overview/ in the gorai-docs repository. You need Go 1.25+ to build gorai. That's it. macOS: brew install go Ubuntu/Debian: sudo apt update && sudo apt install -y golang-go Or download from https://go.dev/dl/ https://go.dev/dl/ for the latest version. NATS is embedded in the gorai binary -- no external message broker to install. The NATS CLI lets you subscribe to messages and debug your robot: macOS: brew install nats-io/nats-tools/nats Linux: go install github.com/nats-io/natscli/nats@latest go install github.com/emergingrobotics/gorai/cmd/gorai@latest Clone the template or click "Use this template" on GitHub git clone https://github.com/emergingrobotics/gorai-robot-template.git my-robot cd my-robot Update the module path to your own go mod edit -module github.com/yourorg/my-robot The template includes a skeleton robot.json . Add components as needed: { "version": "2", "robot": {"name": "my-robot", "description": "My first robot "}, "nats": {"embedded": true, "url": "nats://localhost:4222"}, "dashboard": {"enabled": true, "listen": ":10101"}, "components": } make validate Check configuration make run Run in development mode The embedded NATS server starts automatically -- no separate process needed. Build for Raspberry Pi make build TARGET=linux/arm64 Deploy make deploy DEPLOY HOST=pi@raspberrypi For multi-robot deployments or shared brokers, point at an external NATS server: { "nats": { "url": "nats://nats-server.local:4222", "external": true } } When external is true or the URL points to a non-local address, gorai connects to the external server instead of starting its own. | Platform | AI Performance | Cost | Best For | |---|---|---|---| Raspberry Pi 5 8GB | External Hailo 13-26 TOPS | ~$160 | Primary platform, best ecosystem | Raspberry Pi 5 4GB | External Hailo 13-26 TOPS | ~$100 | Budget builds | Orange Pi 5B 8GB | 6 TOPS built-in NPU | ~$145 | Budget AI builds | Not supported: Pi 3, Pi Zero See Hardware Requirements in the gorai-docs https://github.com/emergingrobotics/gorai-docs/tree/main/docs/specifications/ repository for details. Gorai supports two patterns for accessing hardware. Both produce components with identical interfaces — application code doesn't know or care which is used. Co-processor RP2040 via GSP/2 : An RP2040 microcontroller handles real-time hardware I/O PWM, motor control, encoders . The RPi communicates with it over USB serial using the Gorai Serial Protocol v2. Best for timing-critical control, isolating hardware from Linux scheduler jitter, and reliability-critical applications e.g., an autonomous submersible — motor control must not glitch underwater . Native RPi hardware GPIO/I2C/SPI : Direct access to Raspberry Pi GPIO pins, I2C buses, and SPI buses from Go code. Best for simple sensors, I2C devices, prototyping, and cost-sensitive builds where an RP2040 is unnecessary. Both patterns can be used simultaneously — e.g., RP2040 handling motors while the Pi reads I2C sensors directly. | Command | Description | |---|---| gorai validate