Fullive-AI/Anima: an Agent OS for Xiaomi MIoT hardware

The problem Anima targets: hardware that waits for commands

The README frames the project against a specific gap. Smart hardware already ships with sensors, network connectivity and actuators, yet in the project's words most devices "still wait passively for commands." A light is on or off. A humidifier runs at a level someone picked. The intelligence, if there is any, lives in a vendor app with fixed rules.

Anima is aimed at people who want the decision layer to sit on their own network instead. The README describes it as "an intelligent hardware Agent Runtime running inside your local network" that discovers devices, keeps device state, and controls real hardware through adapters. The intended audience is not someone who wants a prettier remote control. It is someone who owns several device types and wants them to react to environment, habit and each other.

The naming choice is stated plainly: Anima is Latin for "soul," and the project's stated goal is to move hardware "from a connected device to a collaborative intelligent agent." That is a positioning claim rather than a technical one, and the rest of the README is where it has to earn it.

How the Brain, Skills and Adapters fit together

The runtime has three named layers, and the README is explicit about what each one is allowed to do.

The Brain is the decision layer. According to the README it merges user conversations, device state, environment signals, memory and skill capabilities into executable plans, with a LangGraph-based planner and executor, a chat entrypoint at /api/chat, and scheduled ticks for proactive checks. The important constraint is stated directly: the Brain's purpose "is not to let an LLM control devices freely." It decides inside skill boundaries, device capabilities and safety rules. That is a design choice worth taking seriously, because it means the LLM is a planner constrained by code, not an agent with a raw device handle.

A Skill is the unit of device intelligence. The README gives its layout: SKILL.md for metadata and operating rules, a references directory holding knowledge.md, decide.md and learn.md, and scripts/actions.py as the structured action entrypoint. Built-in skills cover light, humidifier, air_conditioner, air_purifier and speaker. The separation matters: domain knowledge lives in markdown prompts, execution lives in Python, and the Brain reads both.

Adapters map structured actions onto real protocols. The README names Mi Home / MIoT as the currently supported ecosystem and says more will be added. The repository layout backs this up with a top-level adapters/ directory and an optional miot dependency in pyproject.toml. There is also an MQTT broker in the stack, and docker-compose.yml wires core to a mosquitto service on port 1883, which suggests device or component messages flow over MQTT rather than only through direct calls.

Installing Anima with Docker Compose

The repository ships a docker-compose.yml with three services: mqtt, core and dashboard. Core builds from the root Dockerfile and listens on 8080 inside the container, mapped from ${ANIMA_API_PORT:-8080}. The dashboard maps ${ANIMA_DASHBOARD_PORT:-3000} to port 80 in its container. The compose file reads several variables from the environment, including the LLM and Xiaomi settings below.

ANIMA_LLM_API_KEY: ${ANIMA_LLM_API_KEY:-}
ANIMA_LLM_MODEL: ${ANIMA_LLM_MODEL:-gpt-4o}
ANIMA_LLM_BASE_URL: ${ANIMA_LLM_BASE_URL:-}
ANIMA_XIAOMI_CLOUD_USER: ${ANIMA_XIAOMI_CLOUD_USER:-}
ANIMA_XIAOMI_CLOUD_PASS: ${ANIMA_XIAOMI_CLOUD_PASS:-}

Then bring the stack up. The mqtt service has a healthcheck that publishes to the anima/healthcheck topic, and core waits for it to report healthy before starting.

docker compose up -d

Core's own healthcheck calls http://127.0.0.1:8080/health inside the container, so a successful startup shows that endpoint answering. The README says the LLM backend can be any OpenAI-compatible service, naming OpenAI, DeepSeek, Doubao, Anthropic through a proxy, and local Ollama-compatible endpoints. Set ANIMA_LLM_BASE_URL when you are not pointing at OpenAI directly.

Running Anima from source with uv and pnpm

If you would rather not containerise, package.json defines the development scripts. The postinstall hook runs uv sync with the dev extra pinned to Python 3.13, so installing the Node-side tooling also prepares the Python virtual environment.

pnpm install
pnpm run dev:broker
pnpm run dev:backend
pnpm run dev:frontend

The broker script runs .venv/bin/amqtt -c amqtt.yaml, the backend runs .venv/bin/python -m core.main, and the frontend runs the dashboard workspace through pnpm. There is also a combined pnpm run dev that goes through scripts/dev.mjs if you want all three under one command. The CLI entrypoint is registered in pyproject.toml as anima, mapping to core.main:cli_entry, so an installed environment also gives you an anima command.

Python support is declared as >=3.11,<3.14, which is narrower than many projects. The Dockerfile uses python:3.13-slim, and the dev flow pins 3.13, so 3.13 is the path of least resistance. The miot adapter is an optional extra, installed in the image via uv sync --frozen --no-dev --extra miot.

Where Anima is the wrong tool

The clearest limitation is hardware coverage. The README states that Anima currently supports Mi Home / MIoT devices and that more protocols will be added over time. If your home is built on Zigbee2MQTT, Home Assistant integrations, Matter or HomeKit, nothing in the README says those work. The adapters directory exists, but a directory is not an implementation, and the README does not document a stable adapter interface for third parties.

The second limitation is the LLM dependency. The Brain needs an OpenAI-compatible endpoint, and the compose defaults point at gpt-4o with an empty API key. That means an Anima deployment has an external network dependency for decisions unless you run a local Ollama-compatible endpoint. If your network is offline or your endpoint is slow, the decision layer is affected, and the README does not describe a fallback rule engine for that case.

Third, the project is at version 0.1.0 in both pyproject.toml and package.json, with no releases retrieved. The repository does carry ARCHITECTURE_GUARDRAILS.md and a SECURITY.md, which suggests the maintainers think about boundaries, but there is no published upgrade path in the README. Treat a first install as an experiment on a network you can afford to disturb.

Anima compared with Home Assistant

The honest comparison is Home Assistant, because that is what most people considering Anima already run. The difference is where intelligence lives. Home Assistant is an integration and automation platform: you write automations, and the platform executes them deterministically. Anima inverts that. The Brain plans from device state, memory and skill knowledge, and the Skills then convert those decisions into structured actions.

That inversion has costs. Home Assistant's automations are inspectable and reproducible; the same trigger produces the same action. An Anima decision passes through an LLM, so the same environment can produce different plans, bounded by skill rules but still not byte-identical. For a hallway light that is fine. For anything where you need a guarantee, an explicit automation is the safer instrument.

The other difference is scope. Home Assistant covers a long list of ecosystems. Anima covers Mi Home / MIoT today and says more are coming. If your devices are already in Home Assistant and your problem is coverage, Anima does not solve it. If your problem is that your automations cannot reason about comfort, season or habit without you writing every branch, the Skill and Memory design is the part worth evaluating.

Licence, maintenance and upgrade cost

Anima is licensed Apache-2.0, declared in pyproject.toml and shipped as a LICENSE file at the repository root. For most users that means you can run it, modify it and redistribute it, with the usual obligations around notices and the patent grant. If you plan to embed it in a product, read the licence text itself rather than this summary. Nothing here is legal advice.

The repository is not archived, and the last push was on 2026-08-20. That is recent enough that the codebase is moving, which cuts both ways: fixes arrive, and interfaces can change under you. The version numbers in pyproject.toml and package.json both read 0.1.0, and no releases were retrieved, so there is no tagged upgrade path to follow. Upgrading means tracking main.

The concrete upgrade cost sits in two places. Skills are markdown plus Python in skills/, mounted into the container by docker-compose.yml, so local skill edits survive image rebuilds but can conflict with upstream changes to the same files. Runtime state lives in ./data, also bind-mounted, and the Dockerfile creates data/memory/users/default, which tells you memory is written to disk and is yours to back up. Before upgrading, copy data/ and diff your skills/ against the new tree.

Editorial conclusion

Adopt Anima if you already own Mi Home or MIoT devices, have an OpenAI-compatible LLM endpoint, and are comfortable running an unreleased 0.1.0 stack on your own network. Do not adopt it if your hardware is Zigbee-only, HomeKit, or Matter, because the README names only Mi Home / MIoT support and says further protocols are still to come. Before installing anything, confirm that python-miio can obtain tokens for your specific device models, that your LLM endpoint is reachable from the machine running core, and that ports 8080, 3000 and 1883 are free. The project's own architecture guardrails file, ARCHITECTURE_GUARDRAILS.md, is the first place to read when you plan to change the Brain or add a Skill.

Frequently asked questions

Official sources

1. Fullive-AI/Anima on GitHub
2. Issues
3. License: Apache-2.0
4. README