Go-based Robotics Framework built around NATS.io
Gorai: A NATS-Powered Robotics Framework in Go
Gorai is designed as the definitive robotics platform for the age of Artificial Intelligence.
Traditionally, we treat a robot as a single entity, but in reality, it is a distributed network consisting of Single Board Computers (SBCs), Microcontroller Units (MCUs), various sensors, and occasionally a remote base station. Gorai ignores the illusion of a single machine. Instead, it treats every actuator and sensor as a discrete service operating on a NATS mesh. These services are discovered dynamically at runtime and addressed by name, eliminating the need for manual wiring.
The core philosophy is simple: the same rigorous disciplines that ensure cloud system reliability—such as location transparency, health monitoring, service discovery, fan-out, and stream replay—are precisely what modern robotics require.
Core Concepts & Architecture
In the Gorai ecosystem, the relationship between the system and its parts can be expressed as:
- Resources & Tools: Sensors are viewed as resources to be read; actuators are viewed as tools to be invoked.
- Native Capabilities: Any agent on the mesh can perceive and interact with the environment. This mirrors the capability model found in MCP (Model Context Protocol), but it is delivered natively via NATS, removing the need for an intermediary MCP server.
- Hardware Agnostic: Because capabilities are identified by name rather than physical location, a single "robot" can actually be a composite of a drone, a rover, a compute box, and a sensor mast. These components join or leave the mesh at runtime, allowing the system to degrade gracefully.
- First-Class Data: State streams, action logs, and replay functionality are integrated into the platform's foundation, not added as afterthoughts.
AI Integration and Safety
While AI execution is encouraged, it is never implicitly trusted.
- Safety Enforcement: Security and safety constraints are handled at the capability node level, not by the AI agent.
- Hybrid Control: The system is agent-compatible but not agent-dependent. Deterministic rule-based planners and state machines utilize the same capabilities as AI agents.
Documentation for Humans and Machines
The project includes an extensive knowledge base: strategy guides, architectural specs, hardware analysis, and a 20-chapter book. All of this is indexed for both people and AI. By pointing an AI agent at the repository, it can autonomously navigate over 100 documents using CLAUDE.md and INDEX.md.
Understanding the Two Binaries
It is critical to distinguish between the two different binaries used in a Gorai project:
1. The Robot Binary
This is the actual application that resides on your hardware (e.g., a Raspberry Pi).
- Nature: A custom Go module.
- Structure: A
main.gofile that uses blank-imports for desired components and executesgorai.Run(). - Deployment: It is a single, static binary containing the embedded NATS server, the mesh, and all components. It requires no external tools to run.
2. The Gorai CLI
This is a developer's utility run on a workstation (similar to kubectl). It handles the orchestration and management around the robot binary.
| Goal | Command | Internal Action |
|---|---|---|
| Prevent config errors | gorai validate robot.json | Checks RDL schema and deprecations before deployment. |
| Rapid Iteration | gorai run robot.json | Runs the runtime in the foreground; bypasses the compile/copy cycle. |
| Create Production Build | gorai build robot.json --target linux/arm64 | Handles cross-compilation, versioning, and validation. |
| Manage Components | gorai component search/add | Manages go get and updates blank-imports in main.go. |
| Live Inspection | gorai mesh services / watch / schemas | Introspects a live NATS mesh to debug a running fleet. |
Getting Started
To get a robot running on a Linux host (like an Orange Pi 5 or Raspberry Pi 5), follow these steps:
- Step 1: Install the CLI (Developer tool)
go install github.com/emergingrobotics/gorai/cmd/gorai@latest
- Step 2: Initialize Project
git clone https://github.com/emergingrobotics/gorai-robot-template.git my-robot
cd my-robot
- Step 3: Configure and Test
gorai validate robot.json
gorai run robot.json
- Step 4: Deploy to Hardware
gorai build robot.json -o robot --target linux/arm64
scp robot pi@raspberrypi: ~
ssh pi@raspberrypi ./robot
Note: There are no containers and no external dependencies—just one binary. For complex setups, multiple binaries can be pointed at a shared NATS bus to create a multi-platform logical robot.
Hardware & Ecosystem
Target Domains: Gorai is built for prosumer-grade field robotics, including:
- Marine: Autonomous Surface Vessels (ASVs).
- Underwater: Autonomous Submersibles (running on Linux hosts inside pressure housings).
- Land: Various autonomous ground vehicles.
The Component Model:
Gorai adopts the Caddy model for packaging. Your project remains a standard Go module, and components are integrated via the import list in your main.go file.