Autonomous OS: A Robot Operating System That Thinks in Markdown
The open-source operating system for robots — install it and your robot comes alive
At a glance
- What is it?
- Autonomous OS turns a robot into an agent by running a reasoning engine on-device and letting skills act through text markers. It is a modular stack for hobbyists and researchers who want a swappable, skill-based robot brain.
- Who is it for?
- Adopt Autonomous OS if you want a robot that reasons on-device and you are willing to define its body, soul, and safety in markdown files. Skip it if you need a deterministic, safety-certified control system or if you expect plug-and-play support for arbitrary hardware.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- autonomous-ai/autonomous-os569 ★ · +354
| Repository | 2026-08-26 | 2026-11-15 |
|---|---|---|
| autonomous-ai/autonomous-os | 215 | 569 |
354 Stars in the last 81 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The Problem: Scripted Robots vs. Autonomous Agents
Most robots are not autonomous in the sense this project uses the word. They follow remote control or scripted demos, and someone has to drive them. Autonomous OS aims to change that by putting an agentic reasoning engine on the robot itself. The README states that everything the robot sees and hears goes to a runtime like Hermes or Claude Code, which decides what to do next. The target user is a developer or researcher who wants a robot that can act on its own, not a manufacturer building a safety-certified industrial machine. The project is explicit that autonomy means the robot thinks, acts, and grows, and it frames itself as the Android for robots, meaning a customizable, app-like ecosystem.
The Architecture: Four Markdown Files Define the Robot
The core design is that any robot can be described in four markdown files. ROBOT.md declares the body, the board, and the hardware. SOUL.md defines the self, who the robot is and how it talks. SAFETY.md sets bounds like speed, brightness, and quiet hours. SKILL.md describes one thing the robot can do. This is a radical simplification. The OS mounts exactly what ROBOT.md declares, and if a required driver is missing, it fails loud. The layers are strict: apps talk to os-server on port 5000, skills write markers instead of touching GPIO, and the agentic runtime sits above all. This separation means you can swap the engine, model, voice, skills, or board without touching the other layers. The markdown-as-config approach is unusual and makes the system readable, but it also means your robot's behavior is only as precise as your prose.
How Skills Work: Text Markers, Not Hardware Calls
A skill is a folder with one SKILL.md file, and the agent reads that markdown to decide what to do. The key mechanism is that a skill acts by writing [HW:/path:{json}] markers in its reply. The os-server strips these markers and POSTs them to HAL before the words are spoken. This means a skill never touches a servo bus or a GPIO pin directly. It is a clean abstraction: the agent produces text, the system interprets the markers, and HAL executes the hardware action. The README gives examples of skills like guard, face-enroll, servo-tracking, and scene. This design has a trade-off. It makes skills safe to write and portable across robots, but it adds a layer of indirection that could introduce latency or ambiguity. A marker that is slightly malformed could fail silently or cause an unintended action, though the README does not detail error handling for markers.
Getting It Running: Tested Robots and One-Command Install
The quickest path is to buy the Autonomous Lamp, which ships with the OS. For existing hardware, the README shows a Reachy Mini install. You SSH in with ssh [email protected], then run curl -fsSL https://raw.githubusercontent.com/autonomous-ai/autonomous-os/main/robots/reachy-mini/install.sh | sudo bash. Nothing is flashed; the Reachy daemon keeps the motors. Then you add the robot in the app by giving it reachy-mini.local. The Intern is another device, but it is not open hardware. For a bring-your-own-robot approach, you follow the full guide, which is linked but not reproduced. The install script is the only concrete command given. There is no mention of building from source or running on a Raspberry Pi, so the supported hardware list is narrow: Lamp, Reachy Mini, Intern, and whatever you can describe in markdown.
The Runtime Zoo: Six Engines Behind One Gateway
The agentic runtime is not a single engine. The repo contains six: Hermes, OpenClaw, PicoClaw, Codex, Claude Code, and OpenCode. They sit behind a 76-method AgentGateway. The gateway reads SOUL.md and installed skills, and you can switch engines live from the web UI. The README claims that persona, memory, and connectors move with the switch. This is a strong promise. It means you can start with a local model like Hermes and move to Claude Code without rewriting your skills. The trade-off is that a 76-method interface is large, and each runtime must implement it fully. The README does not say how complete each implementation is, or whether some runtimes are stubs. If you rely on a specific engine, you should check its folder in the runtimes directory before committing.
Realtime Voice and the Safety Gate
Voice is handled by a realtime layer inside HAL, supporting Gemini Live, OpenAI Realtime, or Qwen. A spoken turn lands here first, and it can answer directly or hand the turn up to the engine. This is a sensible design for low-latency interaction. The safety gate is a pure function of SAFETY.md, and it sits below the engine in every request path. The README truncates the description, but it mentions brightness, quiet hours, and exp (likely expiration or exposure). This is the most important part of the system for real-world use. A pure function means it is deterministic and testable, which is good. But the README does not specify what happens when a safety constraint is violated. Does the robot refuse, degrade, or shut down? That is a gap you must verify before deploying on hardware that moves.
Limitations and Wrong Tool Cases
The most obvious limitation is that the OS is not a real-time control system. It is an agentic layer on top of hardware, and the README does not claim any hard real-time guarantees. If you need a robot arm to stop within milliseconds of a safety event, this is the wrong tool. The safety gate is a pure function, but it sits in a request path with an LLM in the loop, so end-to-end latency is unpredictable. Another limitation is the narrow tested hardware. The README only shows Lamp, Reachy Mini, and Intern. Bring-your-own-robot requires you to write four markdown files, but there is no guarantee your board is supported. The repository has a boards.json in hal/board, but the README does not list supported boards. You must check that file and the capabilities contract yourself. Finally, the learning loop and memory features are described in marketing terms, but the README does not explain how the learning loop works technically, so you cannot evaluate its reliability.
Alternatives: ROS 2 vs. Agentic Markdown
The main alternative is ROS 2, the standard robot operating system. ROS 2 uses a graph of nodes communicating via topics and services, with strict typed interfaces and a mature ecosystem for drivers, navigation, and manipulation. Autonomous OS uses markdown files and text markers for behavior, which is far more flexible for agentic tasks but far less precise for control. ROS 2 gives you deterministic message passing and real-time capabilities, while Autonomous OS gives you an LLM that decides what to do. If you are building a robot that must perform a repetitive task with exact timing, ROS 2 is the safer choice. If you want a robot that can hold a conversation and improvise, Autonomous OS is closer to that goal. The two are not mutually exclusive; the README shows Reachy Mini running the OS beside its own stack, so you could use both.
Maintenance, Upgrades, and Licensing
The project is under Apache-2.0, which is permissive and allows commercial use, but you should read the license yourself. The repository has recent releases, v0.1.6 from August 2026, and a separate wheel for aec-audio-processing. The update mechanism is OTA via a system service called bootstrap, which is its own binary. This means upgrades are handled by the OS itself, not by you manually pulling from Git. The README claims that when a better component ships, your robot gets it the same day without new hardware. That is a strong claim, and it depends on the OTA service working reliably. You should verify that the bootstrap binary is signed and that you control the update channel, especially for a robot that moves. The cost of maintenance is tied to the markdown files: if you change your robot's hardware, you must update ROBOT.md and ensure the capabilities match. There is no mention of a migration path for skills across OS versions, so expect to test skills after each upgrade.
Editorial conclusion
Adopt Autonomous OS if you want a robot that reasons on-device and you are willing to define its body, soul, and safety in markdown files. Skip it if you need a deterministic, safety-certified control system or if you expect plug-and-play support for arbitrary hardware. Before adopting, verify that your board appears in boards.json, that the 13 declared capabilities match your sensors, and that the 76-method AgentGateway supports the runtime you intend to use. Then start by writing a ROBOT.md and running the install script for a tested robot like Reachy Mini, not by building from scratch.
Frequently asked questions
What is Autonomous OS?
It is an open-source operating system for physical AI agents, described as an operating system for robots that gives a robot a voice, vision, memory and skills and then connects it to agents and apps on your computer. The OS runs on the robot and coordinates hardware and agent tasks, while model inference may use remote services depending on your configuration.
Which robots does Autonomous OS run on?
Three are documented: Autonomous Lamp, which ships with the OS and sees, hears, speaks and moves; Reachy Mini, Hugging Face's desk robot, which runs the OS beside its own stack without anything being flashed; and Autonomous Intern, an always-on desk agent with a microphone, speaker and LED ring. There is also a bring-your-own-robot path and a robot comparison document.
How does Autonomous OS decide whether to answer locally or call the model?
For normal voice requests and text-only Web or MQTT chat, local rules run first and then the Jev intent fallback, which is enabled by default. The OS validates the selected command, parameters, confidence and device capabilities before executing, and uncertain requests continue to the main agent. Context-dependent follow-ups bypass intent handling entirely.
Can Autonomous OS operate apps on my Mac?
Yes, through the computer-use skill and a paired Autonomous Buddy. Buddy bundles a Cua Driver for accessibility observations and actions with screenshot support for visual tasks, and the division of labour is that the device agent owns the task while Buddy executes on the Mac. Harness and Buddy have separate connections and separate pairing.
What is SOUL.md in Autonomous OS?
It is where a robot's personality is defined, and editing it changes who the robot is on the next turn. Each robot has its own copy, at robots/lamp/SOUL.md for the Lamp and /opt/devices/reachy-mini/SOUL.md for the Reachy Mini, while ROBOT.md describes the hardware and hal/board/boards.json declares the board.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/autonomous-ai-autonomous-os)Star history chart for your README
[](https://hysenlabs.com/projects/autonomous-ai-autonomous-os)Was this useful?