Skip to content
Back to search

Anima

Make Every Hardware Intelligent — an open-source Agent OS for hardware intelligence

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fullive-ai--anima/badge.svg)](/listings/fullive-ai--anima)

HTML

<a href="/listings/fullive-ai--anima"><img src="/api/listings/fullive-ai--anima/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Docker Compose (recommended)

The only requirement is Docker Desktop, or Docker Engine with the Compose plugin.

git clone https://github.com/Fullive-AI/Anima.git
cd Anima
docker compose up -d --build --wait

No API key is required for the containers to start. Configure an OpenAI-compatible LLM from the Dashboard settings page after startup, or copy `.env.example` to `.env` before running Compose.

After startup, open:

Dashboard: http://localhost:3000
Backend API: http://localhost:8080
Swagger: http://localhost:8080/docs

Useful operations:

docker compose ps          # Check service health
docker compose logs -f     # Follow logs
docker compose down        # Stop the deployment; persisted data is retained

The Compose deployment builds the Dashboard and MIoT-enabled backend, starts Mosquitto, and persists runtime data under `data/` and custom skills under `skills/`.

Local Development Requirements

- Node.js >= 18 - pnpm >= 8 - Python >= 3.11 - uv

`pnpm install` installs Python dependencies through `uv sync`. To control MIoT devices, run `uv sync --extra dev --extra miot --python 3.13`, or change `postinstall` to include `miot`.

Install and Run for Development

git clone https://github.com/Fullive-AI/Anima.git
cd Anima
pnpm install
pnpm dev

After startup, open:

Dashboard: http://localhost:3000
Backend API: http://localhost:8080
Swagger: http://localhost:8080/docs

Configure the LLM

You can configure it in `.env` or in the Dashboard settings page.

ANIMA_LLM_API_KEY=sk-xxx
ANIMA_LLM_MODEL=gpt-4o
ANIMA_LLM_BASE_URL=
ANIMA_LLM_DISABLE_THINKING=false

Anima uses an OpenAI-compatible API, so it can connect to OpenAI, DeepSeek, Doubao, Ollama-compatible endpoints, or other proxy services.

Connect Xiaomi Devices

The recommended path is Xiaomi QR login in the Dashboard:

1. Open the Dashboard settings page. 2. Go to the Xiaomi / Mi Home configuration area. 3. Generate a QR code. 4. Scan it with the Mi Home app. 5. Devices are synchronized automatically when Xiaomi Cloud returns tokens; devices without returned tokens can still be activated by manually entering a token.

If you already know a device IP and token, you can also add a MIoT device manually.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 495 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="docs/images/Anima Logo.svg" alt="Anima logo" width="320" />
  3. <h1></h1>
  4. <p><strong>Make every hardware intelligent</strong></p>
  5. <p>An open-source Agent OS for hardware intelligence.</p>
  6. [English](./README.md) | [中文](./README.zh-CN.md)
  7. <br/><br/>
  8. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
  9. ![Python](https://img.shields.io/badge/Python-3.11--3.13-blue)
  10. ![FastAPI](https://img.shields.io/badge/FastAPI-Backend-009688?logo=fastapi)
  11. ![React](https://img.shields.io/badge/React-Dashboard-61DAFB?logo=react)
  12. ![LangGraph](https://img.shields.io/badge/LangGraph-Agent%20Brain-purple)
  13. ![MIoT](https://img.shields.io/badge/Xiaomi%20MIoT-Supported-orange)
  14. </div>
  15. <br/>
  16. **Anima** is an open-source Agent OS for intelligent hardware. Its goal is not to build yet another device control panel, but to give home hardware perceptive, decision-making, learning, and extensible AI capabilities.
  17. The name **Anima** comes from Latin and means "soul." It reflects the project's original idea: today's smart hardware already has sensors, connectivity, and actuation, but most devices still wait passively for commands. Anima connects these devices to a runnable intelligence center, so lights, air conditioners, humidifiers, air purifiers, speakers, and future devices can understand the environment, the user, and each other.
  18. > Anima's vision: move every piece of hardware from a "connected device" to a collaborative intelligent agent.
  19. <div align="center">
  20. <img src="docs/images/bedroom.svg" alt="Anima Dashboard Bedroom Design" width="100%" />
  21. </div>
  22. ## What Is Anima
  23. Anima can be understood as an intelligent hardware Agent Runtime running inside your local network:
  24. - It discovers devices, maintains device state, and controls real hardware through adapters.
  25. - It maintains long-term Memory and learns from explicit preferences and repeated behavior.
  26. - It uses an LLM Brain to read the environment, user intent, historical memory, and skill knowledge, then plan actions.
  27. - It packages domain knowledge for each device type as a Skill, so decisions are not just "on/off" but aligned with context, comfort, and safety boundaries.
  28. - It provides a Dashboard, REST API, and CLI so you can observe, debug, control, and extend the whole system.
  29. Anima currently supports Mi Home / MIoT devices. More hardware protocols will be added over time, and contributions from the open-source community are welcome.
  30. ---
  31. ## Why Anima
  32. <div align="center">
  33. ![Zero config](https://img.shields.io/badge/Zero%20config-Auto%20discovery-0A7EA4?style=for-the-badge)
  34. ![AI skills](https://img.shields.io/badge/AI%20skills-Per%20device-1B5E20?style=for-the-badge)
  35. ![Memory system](https://img.shields.io/badge/Memory%20system-Learns%20your%20habits-B71C1C?style=for-the-badge)
  36. ![LLM brain](https://img.shields.io/badge/LLM%20Brain-OpenAI%20API%20compatible-4A148C?style=for-the-badge)
  37. ![Skill system](https://img.shields.io/badge/Skill%20system-Extensible-0D47A1?style=for-the-badge)
  38. ![Dashboard](https://img.shields.io/badge/Dashboard-Realtime%20visibility-6A1B9A?style=for-the-badge)
  39. </div>
  40. > [!TIP]
  41. > Most smart-home systems ask, "What sensors do you need?" Anima asks, **"What do you have? I'll use it."** It discovers your devices automatically, loads domain knowledge for each device, and starts making intelligent decisions from day one.
  42. <details>
  43. <summary><strong>Q: Do I need to configure devices manually?</strong></summary>
  44. **A:** No. Anima scans the local network through the corresponding adapter protocols. For Xiaomi / Mi Home devices, one QR login can automatically obtain device tokens without manually entering IP lists or extracting tokens.
  45. </details>
  46. <details>
  47. <summary><strong>Q: Is it just a fancy switch controller?</strong></summary>
  48. **A:** Far from it. Core device types have dedicated **Skills**: domain knowledge packages that include comfort models, occupancy awareness, cross-device coordination rules, and preference learning. Your humidifier understands seasonal adjustments and AC interaction; your lights can follow circadian lighting patterns.
  49. </details>
  50. <details>
  51. <summary><strong>Q: How does it learn my preferences?</strong></summary>
  52. **A:** Anima maintains a memory system with `preferences.md`, normalized learned profiles per device type, and extracted topic memories. The Brain incrementally extracts preferences from interaction history and evolves behavior over time.
  53. </details>
  54. <details>
  55. <summary><strong>Q: Which LLM providers are supported?</strong></summary>
  56. **A:** Any OpenAI-compatible API service, including OpenAI, DeepSeek, Doubao, Anthropic through a proxy, and local Ollama-compatible endpoints. Set `ANIMA_LLM_API_KEY`, and optionally `ANIMA_LLM_BASE_URL`.
  57. </details>
  58. ---
  59. ## System Architecture
  60. Anima's overall runtime flow is driven by user requests, device discovery, sensor updates, scheduled tasks, and device actions. After signals enter Anima Core, the Brain combines device state, Memory, and Skill context to understand and plan. During execution, Skills convert decisions into structured actions, and Adapters map those actions to concrete hardware protocols, completing real device control and feedback recording.
  61. <div align="center">
  62. <img src="docs/images/architecture.svg" alt="Anima Overall Architecture" width="100%" />
  63. </div>
  64. ---
  65. ## Core Highlights
  66. ### 1. Brain: Central Decision Layer
  67. The Brain is Anima's intelligence center. It merges user conversations, device state, environment signals, memory, and skill capabilities into executable plans.
  68. The current Brain supports:
  69. - LangGraph-based planner / executor flows
  70. - Unified chat entrypoint at `/api/chat`
  71. - Scheduled brain ticks for proactive environment checks and automation decisions
  72. - Context construction before skill execution
  73. - State verification and history writes after actions
  74. - OpenAI-compatible LLM backends
  75. The Brain's purpose is not to let an LLM control devices freely. It makes decisions within explicit skill boundaries, device capabilities, and safety rules.
  76. ### 2. Skill: The Smallest Unit of Device Intelligence
  77. A Skill in Anima is not a simple function or a plain prompt. It is a device domain knowledge package, typically including:
  78. ```text
  79. SKILL.md # skill metadata, supported devices, and operating rules
  80. references/
  81. knowledge.md # domain knowledge
  82. decide.md # single-decision prompt
  83. learn.md # long-term learning prompt
  84. scripts/
  85. actions.py # structured action execution entrypoint
  86. ```
  87. Built-in Skills include:
  88. | Skill | Purpose |
  89. |---|---|
  90. | `light` | Light control, brightness, color temperature, circadian lighting |
  91. | `humidifier` | Humidity comfort ranges, seasonal factors, AC interaction |
  92. | `air_conditioner` | Temperature control, comfort and energy balance |
  93. | `air_purifier` | Air quality, purification mode, quiet sleep strategy |
  94. | `speaker` | Audio playback, stop playback, quiet-hour protection |
  95. | `coordinator` | Cross-device coordination |
  96. | `device_discovery` | Device discovery, Mi Home QR login, device activation |
  97. | `skill_creator` | Generate custom skills from natural-language requirements |
  98. You can also add your own skills under `skills/custom/` so Anima can learn new device behaviors or home workflows.
  99. The diagram below shows the full lifecycle of a Skill in Anima: device capabilities can enter the Skill Creator through automatic discovery or user definition, then be organized into the Skill Bank for the Brain to retrieve and select during planning. During execution, the Planner selects an appropriate Skill based on the current environment, device state, and Memory context. The Skill then converts high-level goals into structured actions and applies them to real devices through Adapters. Execution results flow back into Memory and learned profiles, making future decisions more aligned with user habits.
  100. <div align="center">
  101. <img src="docs/images/skill system.png" alt="Anima Skill System Architecture" width="100%" />
  102. </div>
  103. This means a Skill in Anima is not a one-off function call. It is a device intelligence unit that can be created, registered, retrieved, executed, and improved through feedback. When adding a new device type, prefer extending Skills instead of hardcoding device policy into the Brain or an Adapter.
  104. ### 3. Memory: Evidence-Based Long-Term Memory
  105. Anima's Memory system uses a layered design:
  106. ```text
  107. L1 Core Identity
  108. A minimal preference summary loaded on every request, such as preferences_summary.
  109. L2 Memory Directory
  110. A memory directory for the planner, such as available learned profiles and memory topics.
  111. L3 Memory Detail
  112. Detailed long-term memories retrieved by device type and task before skill execution.
  113. ```
  114. The diagram below shows where Memory sits inside the Anima runtime. The lower layer stores preferences, history, learned profiles, and topic memories as files. The middle Memory service reads, extracts, merges, and updates them. The upper layer exposes different memory granularities to the Brain and Skills through `get_planner_context()` and `get_skill_context(device_type)`. This lets the Planner avoid reading all history on every request: it first learns what memories exist, then loads details only when a device Skill is actually executed.
  115. <div align="center">
  116. <img src="docs/images/memory%20system.svg" alt="Anima Memory System Architecture" width="100%" />
  117. </div>
  118. This layered design lets Anima balance long-term learning with context control: L1 stays lightweight, L2 provides a directory, and L3 loads confirmed details only when needed. Execution results, user conversations, and device state continuously enter history, are extracted in the background into more stable long-term memories, and eventually influence future device decisions.
  119. The current memory system supports:
  120. - `history.json` generating an `event_id` for each interaction
  121. - extracted memory stored with a standard schema
  122. - `claim_type` distinguishing explicit preferences, implicit preferences, routines, device aliases, constraints, and home context
  123. - `positive_evidence` / `negative_evidence` recording evidence sources
  124. - `status` distinguishing `candidate`, `confirmed`, `rejected`, and `stale`
  125. - only confirmed memory entering skill decisions by default
  126. - learned profiles stored by device type in `learned.json`
  127. ### 4. Adapter: Real Hardware Integration Layer
  128. Adapters convert Anima's structured actions into real device protocol calls.
  129. Currently supported:
  130. - Xiaomi / Mi Home / MIoT device discovery
  131. - Xiaomi Cloud QR login for device lists and tokens
  132. - Local `ip + token` control for ordinary MIoT devices
  133. - Partial cloud playback support for Xiaomi speakers
  134. - Manual MIoT device addition
  135. - Device state refresh and action result reporting
  136. Note: ordinary MIoT command execution still depends on the device's currently reachable local IP and token. Xiaomi Cloud login is mainly used for discovery and token acquisition; it does not mean every device supports cloud remote control.
  137. ## Features
  138. - **Automatic device discovery**: local network scanning, Xiaomi Cloud device sync, deduplication, and runtime registration.
  139. - **AI decision center**: the LLM Brain generates action plans from environment, devices, skills, and memory.
  140. - **Extensible Skill system**: each device type has independent knowledge, decision prompts, learning prompts, and action scripts.
  141. - **Long-term memory**: candidate memories are extracted from history and promoted to confirmed memory based on evidence.
  142. - **Preference learning**: learned profiles are generated per device type so future decisions better match user habits.
  143. - **Realtime Dashboard**: device list, environment state, chat control, settings, and memory debugging.
  144. - **REST API**: interfaces for devices, chat, settings, scanning, memory, and more.
  145. - **MIoT support**: Xiaomi / Mi Home token acquisition, local control, and partial speaker cloud capabilities.
  146. - **Local-first**: the core runs on your machine and controls devices through the local network whenever possible.
  147. ---
  148. ## Quick Start
  149. ### Docker Compose (recommended)
  150. The only requirement is Docker Desktop, or Docker Engine with the Compose plugin.
  151. ```bash
  152. git clone https://github.com/Fullive-AI/Anima.git
  153. cd Anima
  154. docker compose up -d --build --wait
  155. ```
  156. No API key is required for the containers to start. Configure an OpenAI-compatible LLM from the Dashboard settings page after startup, or copy `.env.example` to `.env` before running Compose.
  157. After startup, open:
  158. ```text
  159. Dashboard: http://localhost:3000
  160. Backend API: http://localhost:8080
  161. Swagger: http://localhost:8080/docs
  162. ```
  163. Useful operations:
  164. ```bash
  165. docker compose ps # Check service health
  166. docker compose logs -f # Follow logs
  167. docker compose down # Stop the deployment; persisted data is retained
  168. ```
  169. The Compose deployment builds the Dashboard and MIoT-enabled backend, starts Mosquitto, and persists runtime data under `data/` and custom skills under `skills/`.
  170. ### Local Development Requirements
  171. - Node.js >= 18
  172. - pnpm >= 8
  173. - Python >= 3.11
  174. - uv
  175. `pnpm install` installs Python dependencies through `uv sync`.
  176. To control MIoT devices, run `uv sync --extra dev --extra miot --python 3.13`, or change `postinstall` to include `miot`.
  177. ### Install and Run for Development
  178. ```bash
  179. git clone https://github.com/Fullive-AI/Anima.git
  180. cd Anima
  181. pnpm install
  182. pnpm dev
  183. ```
  184. After startup, open:
  185. ```text
  186. Dashboard: http://localhost:3000
  187. Backend API: http://localhost:8080
  188. Swagger: http://localhost:8080/docs
  189. ```
  190. ### Configure the LLM
  191. You can configure it in `.env` or in the Dashboard settings page.
  192. ```env
  193. ANIMA_LLM_API_KEY=sk-xxx
  194. ANIMA_LLM_MODEL=gpt-4o
  195. ANIMA_LLM_BASE_URL=
  196. ANIMA_LLM_DISABLE_THINKING=false
  197. ```
  198. Anima uses an OpenAI-compatible API, so it can connect to OpenAI, DeepSeek, Doubao, Ollama-compatible endpoints, or other proxy services.
  199. ### Connect Xiaomi Devices
  200. The recommended path is Xiaomi QR login in the Dashboard:
  201. 1. Open the Dashboard settings page.
  202. 2. Go to the Xiaomi / Mi Home configuration area.
  203. 3. Generate a QR code.
  204. 4. Scan it with the Mi Home app.
  205. 5. Devices are synchronized automatically when Xiaomi Cloud returns tokens; devices without returned tokens can still be activated by manually entering a token.
  206. If you already know a device IP and token, you can also add a MIoT device manually.
  207. ---
  208. ## Common Commands
  209. | Command | Description |
  210. |---|---|
  211. | `docker compose up -d --build --wait` | Build and start the complete deployment |
  212. | `docker compose down` | Stop the Docker deployment |
  213. | `pnpm install` | Install frontend and backend dependencies |
  214. | `pnpm dev` | Start Dashboard, Backend, and local broker together |
  215. | `pnpm dev:frontend` | Start only the frontend |
  216. | `pnpm dev:backend` | Start only the backend |
  217. | `pnpm dev:broker` | Start only the local MQTT broker |
  218. | `pnpm build` | Build the frontend |
  219. | `uv run pytest tests/ -v` | Run tests |
  220. | `uv run ruff check .` | Run Python lint |
  221. ---
  222. ## Project Structure
  223. ```text
  224. Anima/
  225. ├── 🧠 core/ # Backend runtime: API, brain, memory, devices
  226. │ ├── 🛣️ api/ # FastAPI routes and HTTP endpoints
  227. │ ├── 🧭 brain/ # Planner, executor, ReAct agent, skill loader
  228. │ ├── 🔎 devices/ # Discovery orchestration and device registry
  229. │ ├── 📡 events/ # Async EventBus and runtime signals
  230. │ ├── 🤖 llm/ # OpenAI-compatible LLM runtime config
  231. │ ├── 🔊 media/ # Xiaomi speaker playback support
  232. │ ├── 🗃️ memory/ # Preferences, history, profiles, extracted memories
  233. │ ├── ⚙️ runtime/ # Settings and persisted config
  234. │ └── ⚙️ main.py # Application entrypoint
  235. ├── 🔌 adapters/ # Hardware protocol adapters
  236. │ └── 🏠 miot/ # Xiaomi MIoT adapter
  237. ├── ✨ skills/ # Device intelligence packages
  238. │ ├── 🧩 system/ # Built-in skills
  239. │ └── ✍️ custom/ # User-defined skills
  240. ├── 🖥️ dashboard/ # React + Vite dashboard
  241. ├── ✅ tests/ # Automated tests
  242. ├── 📚 docs/ # Design notes and implementation plans
  243. ├── 💾 data/ # Local runtime data
  244. ├── 📦 package.json # Root pnpm scripts
  245. └── 🧰 pyproject.toml # Python project config
  246. ```
  247. ---
  248. ## API Overview
  249. The backend runs at `http://localhost:8080` by default.
  250. Common endpoints include:
  251. | Method | Endpoint | Description |
  252. |---|---|---|
  253. | `GET` | `/health` | Health check |
  254. | `GET` | `/api/devices` | Get the device list |
  255. | `POST` | `/api/devices/{device_id}/command` | Send a command to a device |
  256. | `POST` | `/api/devices/add` | Manually add a MIoT device |
  257. | `POST` | `/api/devices/{device_id}/activate` | Activate a scanned device with a token |
  258. | `POST` | `/api/chat` | Unified chat and task execution entrypoint |
  259. | `GET` | `/api/environment` | Current aggregated environment state |
  260. | `POST` | `/api/environment/refresh` | Refresh device state |
  261. | `POST` | `/api/scan` | Trigger device scanning |
  262. | `GET` | `/api/memory` | Inspect memory, history, and learned profiles |
  263. | `GET` | `/api/settings` | Read settings |
  264. | `POST` | `/api/settings/llm/configure` | Configure the LLM |
  265. | `POST` | `/api/settings/xiaomi/qr/start` | Start Xiaomi QR login |
  266. | `POST` | `/api/settings/xiaomi/qr/poll` | Poll QR login status |
  267. For the full API, open Swagger:
  268. ```text
  269. http://localhost:8080/docs
  270. ```
  271. ---
  272. ## How to Extend
  273. ### Add a Skill
  274. The simplest extension path is to add a skill.
  275. ```text
  276. skills/custom/my_skill/
  277. ├── SKILL.md
  278. ├── references/
  279. │ ├── knowledge.md
  280. │ ├── decide.md
  281. │ └── learn.md
  282. └── scripts/
  283. └── actions.py
  284. ```
  285. A good skill should answer four questions:
  286. ```text
  287. 1. Which devices or scenarios does it apply to?
  288. 2. What domain knowledge does it need?
  289. 3. When should it act, and when should it no-op?
  290. 4. What structured actions can it output?
  291. ```
  292. ### Add an Adapter
  293. Adapters integrate new hardware protocols. The core interface is small:
  294. ```text
  295. discover() # discover devices
  296. subscribe() # refresh or subscribe to state
  297. execute() # execute an action
  298. ```
  299. You can use `adapters/miot/` as a reference to implement new protocol adapters such as Matter, Home Assistant, BLE, HTTP API, or private device protocols.
  300. ---
  301. ## Current Status
  302. Anima is still early-stage, but it already has a complete runnable core loop:
  303. ```text
  304. device discovery -> Brain planning -> Skill decision -> Adapter execution -> state verification -> History/Memory learning
  305. ```
  306. The more mature parts today:
  307. - Core runtime
  308. - Dashboard
  309. - MIoT adapter
  310. - Skill framework
  311. - Memory extraction and learned profiles
  312. - Chat and REST API
  313. Areas still evolving:
  314. - More device protocol adapters
  315. - More complete remote-control strategies
  316. - Stronger memory retrieval and conflict handling
  317. - Skill marketplace / community skills
  318. - Multi-user and permission models
  319. - More complete security policies and deployment experience
  320. ---
  321. ## Update Log
  322. This section records Anima releases, architecture upgrades, and key capability evolution so developers can quickly understand the core changes at each stage.
  323. - 2026-06-01: Anima's first open-source version is released, providing the foundational Agent OS capabilities for intelligent hardware: local device discovery, MIoT device integration, LLM Brain decisions, Skill mechanism, long-term Memory system, and visual Dashboard.
  324. ---
  325. ## Contributing
  326. Anima welcomes different kinds of contributions:
  327. - Add new device adapters
  328. - Write or improve skills
  329. - Optimize Brain decision flows
  330. - Improve the Memory mechanism
  331. - Enhance the Dashboard experience
  332. - Add tests and documentation
  333. - Report real-device compatibility issues
  334. Before contributing, you may want to read:
  335. - [CONTRIBUTING.md](./CONTRIBUTING.md)
  336. - [ARCHITECTURE_GUARDRAILS.md](./ARCHITECTURE_GUARDRAILS.md)
  337. - [docs/plans/design.md](./docs/plans/design.md)
  338. ---
  339. ## Security Notes
  340. Anima connects to real devices and executes real actions. Please note:
  341. - Do not expose the Dashboard or API directly to the public internet.
  342. - Sensitive information such as Xiaomi tokens and LLM API keys should only be stored in trusted environments.
  343. - Establish clear permission boundaries before controlling devices in offices, public spaces, or shared homes.
  344. - Keep automation conservative, especially for high-risk devices such as door locks, security devices, and electrical power.
  345. ---
  346. ## License
  347. This project is licensed under the Apache License 2.0.
  348. See the [LICENSE](./LICENSE) file for details.
  349. <div align="center">
  350. <br/>
  351. <p><em><strong>Anima</strong></em></p>
  352. <p><em>Make every hardware intelligent.</em></p>
  353. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.