Desk companion OS for robots — Talk, Home, House, Device. A fork of Autonomous OS.
Kestrel is this product. Autonomous OS is the upstream stack (HAL, skills, Hermes / OpenClaw, the ROBOT.md contract). We keep that contract. We change what a person at the desk actually uses.
In-app Guide (Device → Guide) is the home-user handbook. The same pages live in docs/wiki/. Builder docs stay in docs/.
| This repo | K95M65/kestrel |
| Upstream | autonomous-ai/autonomous-os |
| File-level overlay | docs/divergence-from-stock.md |
Stock Autonomous OS is a device-agnostic robot OS. Lamp, Intern, and Reachy Mini are bodies. Setup and chrome assume the Autonomous phone app and a Monitor + Settings dump.
Kestrel is a desk companion on that same OS. The robot serves its own product. You name it, talk to it, and give it a life at the desk — without flashing the body or joining an Autonomous account.
Name it, talk to it, let it see you, pick who it is for (Just me / Family / Kids / Office), then mornings.
Talk, Home, House, Device. Hardware, runtime, and MQTT stay behind Advanced / ?debug=true. Ocean on cream (#3368A0 / #F2EFE7), not stock lamp amber.
| Home — quiet hours + uses | Talk |
|---|---|
 |
 |
| House — People | Sign in |
|---|---|
 |
 |
Uses is an OS-owned catalog the brains consume (they do not invent it): chat from your phone, websites on the computer, news and weather, speaker music vs Spotify on the computer, stories, look, dance. Each use has its own onboarding.
Behaviors is how it lives here — life presets and the guided setup, not a Settings dump.
| Uses | Behaviors |
|---|---|
 |
 |
It has a name. Rename writes IDENTITY.md and resets the brain session so the next turn is not still “Reachy.” Wake chips are hey {name}.
People is a contact book. Live add-a-friend, photo and voice on the person — not a Device tab of embeddings.
Kestrel Buddy on the computer you actually use. Mac menu bar, plus Windows and Linux desktop. Same pairing code from Home. The robot opens sites and apps there. (A phone app is a different job — Talk from elsewhere — and is still Telegram today.)
Grok as a first-class brain. Device-code login with a SuperGrok account. Hermes, OpenClaw, Codex, Claude Code, and the others stay swappable.
Claim it like a Home accessory. Home shows a setup code and QR. Scan /claim on the same Wi-Fi. That person is the owner. It does not join Apple Home or Google Home.
Sign in with Google for mail and calendar (TV-style code + QR). Skip with an app password / iCal. Sign in with Apple needs public HTTPS — Advanced.
Hive. Two robots on this Wi-Fi can hear each other in Talk. One hosts; the other pastes the join address (QR on Device → Channels).
Matter via Home Assistant. This robot commissions a bulb; it is not itself a Matter accessory. House → Behaviors → Home Assistant, then paste the code from the box.
Plugins vs skills. Device → Plugins is a short trusted list (dance, emotions, cameraman, phrase teacher). Skills are markdown the brain reads (@skill in Talk). Guide: Compared with Siri and ChatGPT.
Reachy Mini without a flash. Pollen’s daemon keeps the motors. Kestrel sits beside it. Install is one command; undo is documented. Lamp and Intern keep working on the same contract.
We do not take Autonomous’s OTA. A public software-update would overwrite this overlay. Side-load this tree. When stock ships a fix, we port it by hand — docs/divergence-from-stock.md.
What we did not rename: the Go module go.autonomous.ai/os, schema autonomous.device.v1, Buddy bundle ID and pairing folder, Autonomous Lamp / Intern / the Autonomous phone app. Those are protocol and upstream products.
The rest of this page is the stack we forked — why a robot OS exists, which bodies it already runs on, how the layers fit, how to contribute.
Robots have been around for years but have never been autonomous — someone has to drive them with a remote, and they've stopped at scripted demos. Autonomous OS (and this fork) installs on the body and it comes alive.
- Your robot thinks. Everything it sees and hears goes to an agentic reasoning engine running on the robot itself — Hermes, Claude Code, or whichever you choose — that decides what to do next.
- Your robot acts. It guards the house, knows your face, follows you as you move, reads the mood on your face, sets the light — and does the desk work too: Gmail, GitHub, your computer. Each one is a skill — install more from the Skill Store, or write your own.
- Your robot grows. It has a built-in learning loop. It creates skills from experience, sharpens them as it uses them, keeps what it learns, searches its own past conversations, and builds a deeper picture of you with every session.
Every component is swappable — engine, model, voice, skills, board. Your robot declares what it has in a ROBOT.md, and the OS mounts exactly that.
The simplest way in is a robot already tested on this stack. What each of them can do: robot comparison.
Reachy Mini is Hugging Face / Pollen’s desk robot. Kestrel runs beside Pollen’s own stack. Nothing is flashed; the Reachy daemon keeps the motors.
Reach.Mini.and.Autonomous.Lamp.mp4
- SSH in —
ssh pollen@reachy-mini.local. - Run one command.
curl -fsSL https://raw.githubusercontent.com/K95M65/kestrel/main/robots/reachy-mini/install.sh | sudo bash - Open the robot’s own UI at
http://reachy-mini.local(or the LAN IP). Walk Talk / Home / House / Device. The Autonomous phone app can still add a Reachy Mini if you use that path. - Interact with it. Say something — the head tilts, the antennas lift, and it answers.
- Install a skill from the Skill Store, or type what you want it to do and it writes one.
- Give it a character. Edit
/opt/devices/reachy-mini/SOUL.md. How to undo the install:robots/reachy-mini/README.md. - Put it next to a Lamp. Each one hears the other's answer as its next input, so the two of them will hold a conversation until you stop them.
Lamp is Autonomous's own desk robot — it sees, hears, speaks, and moves. Stock images ship Autonomous OS. This fork runs Kestrel on the same contract.
- Add it. In the Autonomous phone app (iOS | Android), tap Add robot → Lamp. Or open the robot's own setup UI.
- Set up Wi-Fi. Pick your network in the app; it joins the robot's hotspot and hands over the keys and pairing.
- Interact with Lamp. Say something, it turns to look at you, the ring lights up, and it answers.
- Install a skill from the Skill Store — one tap, live on the next conversation.
- Build your own skill. Type what you want it to do in the app and it writes the skill.
- Give it a character. Edit
SOUL.mdand it is someone else on the next turn.
Intern is the always-on desk agent: mic, speaker, LED ring.
- Add it. In the app, tap Add robot → Intern.
- Set up Wi-Fi. Same flow as Lamp: pick your network and it handles the keys and pairing.
- Interact with it. Say something and it answers; the ring shows what it is doing.
- Install a skill from the Skill Store.
- Build your own skill. Type what you want in the app; it is live on the next conversation.
- Give it a character. Edit
/opt/devices/intern-v2/SOUL.md.
Kestrel runs on any robot you can describe in four markdown files.
ROBOT.md— the body: the board and the hardware it has.SOUL.md— the self: who it is and how it talks.SAFETY.md— the bounds: how fast, how bright, how late.SKILL.md— the hands: one thing it can do.
Follow the full guide.
Kestrel is a software stack (the Autonomous OS architecture). Each layer uses only the layer below it, so any layer can be replaced without touching the others. Every layer is a folder in this repo.
What a person touches. The robot serves its own setup and monitor UI from system/web/ (Kestrel: Talk, Home, House, Device). The original Autonomous phone app still talks to os-server on :5000.
One folder per behavior, one SKILL.md inside: markdown the agent reads. A skill acts by writing [HW:/path:{json}] markers in its reply, so it never touches a servo bus or a GPIO pin. Each skill declares the capabilities it needs and installs on every robot that has them.
The engine that thinks. Six of them — Hermes, OpenClaw, PicoClaw, Codex, Claude Code, OpenCode — behind one 76-method AgentGateway. It reads the robot's SOUL.md and its installed skills. Switch live from the web UI; persona, memory and connectors move with it.
The Go daemon os-server on :5000, one package per box in the figure. intent answers fixed commands from a local table with no model; server strips [HW:…] markers out of a reply and POSTs them to HAL before the words are spoken; agent switches engines; bootstrap is OTA, its own binary.
Gemini Live, OpenAI Realtime or Qwen, hosted inside HAL and running beside the main path. A spoken turn lands here first: it answers directly, or hands the turn up to the engine.
The 13 names a robot may declare — audio, vision, sensing, presence, motion, light, display, expression, lifelike, media, connectivity, companion, system. Ten mount HTTP routes on :5001 (111 endpoints, live Swagger at /api/hardware/docs); presence and lifelike are loops with no route, companion lives in os-server. HAL mounts only what ROBOT.md declares and fails loud on a missing required driver.
A pure function of SAFETY.md, below the engine and in every request path: brightness, quiet hours, explicit-move speed. No model in the loop — the same clamp whoever asked. What it does not cover yet: docs/safety.md.
One folder per subsystem: motors, rgb, camera, voice, display, sensing, tracking, and the media handover a third-party daemon needs. New hardware is one class and one factory line.
One JSON entry per board, matched against /proc/device-tree/model. Raspberry Pi 4, Pi 5, CM4 and OrangePi 4 Pro today. A new board is an entry, not a code change.
The vendor kernel — Raspberry Pi OS, OrangePi Debian, or the robot's own image. We do not ship one, and nothing above the drivers has a real-time deadline: position control closes in the servo firmware, or in the robot's own daemon.
Four markdown files and a driver per robot. Declarations, not forks — a body is a PR.
Long form: architecture · HAL · device spec · capabilities · safety · developer guide.
The easiest way in is a skill: one markdown file, no Go, no hardware, and it lands on every robot that has the parts. PRs welcome. Upstream Autonomous OS issues still live at autonomous-ai/autonomous-os; this fork is K95M65/kestrel.
| You want to… | You write… | Start from |
|---|---|---|
| Teach every robot something new | skills/<name>/SKILL.md (+ skill.json if it needs hardware) |
skills/guard/ · skill-creator |
| Run Kestrel on your robot | robots/<id>/ROBOT.md + SAFETY.md + SOUL.md |
robots/reachy-mini/ — a third-party port, end to end |
| Support new hardware | a class in hal/drivers/<subsystem>/ + one factory line |
reachy_service.py |
| Support a new board | one entry in hal/board/boards.json |
boards.json |
| Add a brain | an AgentGateway implementation in runtimes/<name>/ |
adding-agent-runtime.md |
Seven more paths — apps, chat bridges, perception models, voices, safety bounds, CTS probes — and the norms: CONTRIBUTING.md. One rule worth knowing up front: robots/contract/ is the interface everyone builds on, so open an issue before you change it.
Build locally:
make os-build && make os-test # Go daemon, cross-compiled to linux/arm64
(cd hal && uv sync) && make hal-dev # HAL on :5001 with reload
make web-install && make web-dev # setup + monitor UI
make cts # is this a valid Kestrel / Autonomous-compatible device?Kestrel is a fork of Autonomous OS. Original work: the Autonomous OS authors (autonomous-ai/autonomous-os). See LICENSE and NOTICE.
Everything outside hal/ is Apache-2.0. hal/ is GPL-3.0, kept that way by choice so the tree has one license per top-level folder; a driver you commit there is GPL, so a closed vendor SDK wraps out of process.
A robot running this carries other people's work: Pollen's reachy_mini SDK, YOLOv8 for tracking (AGPL-3.0 — read it before you ship), TEN-VAD and Silero for hearing, LeRobot and the LeLamp Runtime under the motion code, and the brains we install but do not ship. All of it, including what we copied verbatim: CREDITS.md. Security issues: SECURITY.md.