Agentic home automation system for Home Assistant
100% vibecoded by AI (mostly Claude) and mass quantities of coffee. No humans were mass-harmed in the making of this codebase — just mass-caffeinated.
Project Aether is an intelligent home automation system that connects AI agents to your Home Assistant instance. Instead of writing YAML by hand or clicking through dashboards, you have a conversation — describe what you want, and Aether's agents discover your devices, analyze your energy data, diagnose problems, and design automations for you.
Key idea: An Orchestrator agent classifies user intent and dynamically routes requests to specialized domain agents (Architect, Data Science team, Food, Research, Knowledge, Dashboard Designer, and more). Each agent is configured with the right model, tools, and prompt at runtime. All mutating actions require human approval via the web UI or push notifications (iPhone/Apple Watch).
- Intelligent Orchestration — an Orchestrator agent classifies intent, selects the right domain agent and model tier (fast/standard/frontier), and presents clarification options for ambiguous requests
- Conversational Home Control — chat with your smart home in natural language; all mutating actions require explicit approval (HITL) via web UI or push notification
- Push Notification Approval — mutating actions can be approved/rejected from iPhone or Apple Watch via HA actionable notifications
- Web Search — domain agents can search the web for recipes, prices, documentation, and more via DuckDuckGo
- Dynamic Agent Composition — agents are configured at runtime with DB-backed prompts, tools, and model selection; workflows can be composed on-the-fly
- Entity Discovery — the Librarian agent catalogs all HA entities, devices, and areas into a searchable database
- Automation Design — describe automations in plain English; the Architect designs YAML and presents it for approval before deploying
- Energy Analysis — the DS team's Energy Analyst analyzes consumption patterns via sandboxed Python scripts
- Diagnostics & Troubleshooting — the Diagnostic Analyst investigates error logs, entity health, and integration issues
- Intelligent Optimization — the Behavioral Analyst detects patterns and suggests automations for recurring manual actions
- YAML Schema Validation — structural and semantic validation of automations, scripts, scenes, and dashboards against live HA state
- Smart Config Review — review existing HA configs with improvement suggestions presented as approvable proposal diffs
- Dashboard Designer — generates Lovelace dashboard YAML tailored to your home's entities and areas
- Analysis Reports — detailed reports with artifacts from DS team analysis sessions
- Scheduled & Event-Driven Insights — cron schedules and HA webhook triggers feed into the analysis pipeline
- Agent Activity Tracing — real-time visualization of agent delegation and trace timelines in the chat UI
- Authentication & Passkeys — WebAuthn (Face ID / Touch ID), HA token, password, and API key auth methods
- Multi-Provider LLM — OpenAI, OpenRouter, Google Gemini, Ollama, Together AI, Groq with per-agent model routing and failover
- Full Observability — every agent operation traced via MLflow with parent-child spans, token usage, and latency metrics
- Trace Evaluation — custom MLflow scorers evaluate agent trace quality (latency, safety, delegation depth)
┌─────────────────────────────────────────────────────────────────────────────┐
│ User Interfaces │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────────┐ │
│ │ CLI │ │ REST API │ │ Chat UI (React) │ │
│ │ (aether) │ │ (FastAPI) │ │ localhost:3000 │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────────┬─────────────────┘ │
│ └──────────────────┼───────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ /v1/chat/completions │ (OpenAI-compatible) │
│ │ /api/conversations │ (Native API) │
│ └──────────────┬──────────────┘ │
└─────────────────────────────┼───────────────────────────────────────────────┘
│
┌─────────────────────────────┼───────────────────────────────────────────────┐
│ Agent Layer │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Orchestrator Agent │ ◄── Classifies intent, │
│ │ (classify → plan → route) │ routes to domain agents │
│ └──────────────┬──────────────┘ │
│ │ delegates via tools │
│ ┌──────────┬────────┼────────┬──────────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌───────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐ │
│ │ Data │ │Librarian│ │Developer│ │Dashboard│ │ Schema │ │
│ │ Science │ │ Agent │ │ Agent │ │Designer│ │ Validator │ │
│ │ Team │ │ │ │ │ │ │ │ │ │
│ └─────┬─────┘ └───┬────┘ └───┬────┘ └───┬────┘ └──────┬─────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌───────────┐ ┌────────┐ ┌────────────┐ ┌────────┐ ┌──────────┐ │
│ │ Sandbox │ │ MCP │ │ Automation │ │Lovelace│ │ YAML │ │
│ │ (gVisor) │ │ Client │ │ Deploy │ │ YAML │ │ Schemas │ │
│ └───────────┘ └────────┘ └────────────┘ └────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────┼───────────────────────────────────────────────┐
│ Data Layer │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ PostgreSQL │ │ MLflow │ │
│ │ (State) │ │ (Traces) │ │
│ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────┬─────────────────────────────────┘
│
┌──────────────────────────────────────────┼─────────────────────────────────┐
│ External Services │ │
│ ┌────────────────────────────────┴──────────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Home Assistant │ │ LLM Provider │ │
│ │ (via MCP) │ │ (OpenAI/etc.) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
| Agent | Role | What It Does |
|---|---|---|
| Architect | Orchestrator & Chat | The unified entry point. Handles conversation, routes to specialists, designs automations, reviews existing configs. Has 16 curated tools. |
| Data Science Team | Analysis & Insights | Three specialists: Energy Analyst, Behavioral Analyst, Diagnostic Analyst. Share findings via TeamAnalysis with dual synthesis (programmatic + LLM). Scripts run in gVisor sandbox. |
| Librarian | Discovery & Catalog | Discovers all HA entities, devices, and areas. Builds a searchable local catalog. |
| Developer | Deployment | Takes approved automation proposals and deploys them to Home Assistant. Falls back to manual instructions if the API is unreachable. |
| Dashboard Designer | Dashboard Generation | Designs Lovelace dashboards by consulting the DS team for entity/area data and generating validated YAML configs. |
- Python 3.11+
- uv (Python package manager)
- Podman or Docker (for PostgreSQL, MLflow)
- Node.js 18+ (for the UI)
- A Home Assistant instance with a long-lived access token
- An LLM API key (OpenAI, OpenRouter, or other — see Configuration)
# Clone the repository
git clone https://github.com/dimakis/Project-Aether.git
cd Project-Aether
# Install Python dependencies
make install
# Install UI dependencies
# Requires npm
make ui-install
# Configure environment
cp .env.example .env
# Edit .env with your HA_TOKEN, HA_URL, and LLM_API_KEY# Start everything (infrastructure + API + UI)
make run-ui
# Open the chat UI
open http://localhost:3000That's it. The UI connects to the API at localhost:8000, which talks to your Home Assistant via MCP.
- Open the Chat at
http://localhost:3000and try: "Discover my home" - Browse Entities on the Entities page to see what was found
- Ask a question: "What lights are currently on?" or "Analyze my energy usage"
- Design an automation: "Create an automation that turns on the porch light at sunset"
- Check diagnostics: "Are any of my devices unavailable?"
Aether supports two deployment modes:
All agents run in a single Python process. This is the simplest setup for development and single-user deployments.
make run # Dev: infra in containers, API on host with hot-reload
make run-ui # Dev + React UI
make run-prod # Everything containerizedAgents run as separate containers communicating via the A2A protocol. The monolith acts as an API gateway, delegating to agent services.
make run-distributed # Gateway + Architect + DS Orchestrator + DS AnalystsAPI Gateway :8000 --> Architect :8001 --> DS Orchestrator :8002 --> DS Analysts :8003
Each agent container serves an A2A Agent Card at /.well-known/agent-card.json and health probes at /health.
See Distributed Mode Guide for the full runbook.
| Guide | Description |
|---|---|
| Getting Started | Authentication, deployment modes, remote access |
| Distributed Mode | Running agents as A2A services in separate containers |
| Configuration | LLM providers, per-agent overrides, failover, usage tracking, environment variables |
| Architecture | System design, agent roles, data flows, observability, security model |
| User Flows | Step-by-step interaction sequences for all major features |
| API Reference | All ~120 REST API endpoints |
| CLI Reference | Terminal commands for the aether CLI |
| Development | Dev setup, testing, quality checks, project structure |
| UI Guide | UI pages, tech stack, development |
| Contributing | Workflow, coding standards, branch strategy |
| Security | Vulnerability reporting, security model |
| Data Model | Database schema reference |
| Feature Specs | Individual feature specifications |
| OpenAPI Spec | Machine-readable API contract |
- Safety First (HITL): All mutating Home Assistant actions require explicit human approval. No automation deploys without your "approve."
- Isolation: DS Team analysis scripts run in gVisor sandboxes — no network access, read-only filesystem, enforced resource limits.
- Observability: Every agent action is traced via MLflow with full span trees, token counts, and latency metrics. Custom scorers evaluate trace quality.
- Reliable State: LangGraph + PostgreSQL for checkpointed workflow state. Conversations, proposals, and insights persist across restarts.
- Reliability: Comprehensive testing (unit, integration, E2E) with TDD workflow. 80% minimum unit test coverage target.
- Security: Defence in depth — encrypted credentials (Fernet/AES-256), bcrypt password hashing, Pydantic input validation, parameterized queries, security headers.
MIT