seiggy/lucia-agenthost

Lucia — Autonomous Home Assistant AI

https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet&labelColor=2C003E&color=5656FF]([] https://img.shields.io/badge/Agent%20Framework-1.0.0-blue]([] https://img.shields.io/github/license/seiggy/lucia-dotnet](https://github.com/seiggy/lucia-dotnet/blob/master/LICENSE) https://img.shields.io/badge/Home%20Assistant-Compatible-41BDF5](https://www.home-assistant.io/)

Lucia (pronounced LOO-sha) is an open-source, privacy-focused AI assistant that serves as a complete replacement for Amazon Alexa and Google Home. Built on the Microsoft Agent Framework with a multi-agent architecture, Lucia provides autonomous whole-home automation management through deep integration with Home Assistant.

🎯 Key Features

• 🤖 Multi-Agent Orchestration — Router, dispatcher, and result aggregator coordinate specialized agents using the A2A protocol
• 🧠 Semantic Understanding — Natural language processing using embeddings and semantic search
• 🔒 Privacy First — Fully local operation with optional cloud LLM support
• 🏠 Deep Home Assistant Integration — Native integration via custom component with conversation API and JSON-RPC
• 📊 Management Dashboard — React-based dashboard with 20+ pages for agent management, traces, and configuration
• 🧙 Guided Setup Wizard — Multi-step onboarding with AI provider configuration and connectivity tests
• 📦 Kubernetes Ready — Cloud-native deployment with .NET Aspire, Helm charts, and K8s manifests
• 🔌 Extensible — Script-based plugin system and runtime agent builder with MCP tool integration

Supported Inference Platforms

🚀 Quick Start

Prerequisites

• https://www.docker.com/ and Docker Compose
• Home Assistant instance (2024.12 or later)
• An LLM provider API key (Azure AI Foundry, OpenAI, Ollama, etc.)

Installation

1. Create a docker-compose.yml:

   yaml
   services:
     lucia-redis:
       image: redis:8.2-alpine
       container_name: lucia-redis
       networks: [lucia-network]
       ports: ["127.0.0.1:6379:6379"]
       command: >
         redis-server --appendonly yes
         --maxmemory 256mb --maxmemory-policy allkeys-lru
       volumes: [lucia-redis-data:/data]
       healthcheck:
         test: ["CMD", "redis-cli", "PING"]
         interval: 30s
         timeout: 10s
         retries: 3
       restart: unless-stopped
   
     lucia-mongo:
       image: mongo:8.0
       container_name: lucia-mongo
       networks: [lucia-network]
       ports: ["127.0.0.1:27017:27017"]
       volumes: [lucia-mongo-data:/data/db]
       healthcheck:
         test: ["CMD", "mongosh", "--eval", "db.runCommand('ping').ok"]
         interval: 30s
         timeout: 10s
         retries: 3
       restart: unless-stopped
   
     lucia:
       image: seiggy/lucia-agenthost:latest
       container_name: lucia
       depends_on:
         lucia-redis: { condition: service_healthy }
         lucia-mongo: { condition: service_healthy }
       networks: [lucia-network]
       ports: ["7233:8080"]
       environment:
         - ASPNETCORE_ENVIRONMENT=Production
         - ASPNETCORE_URLS=http://+:8080
         - ConnectionStrings__luciatraces=mongodb://lucia-mongo:27017/luciatraces
         - ConnectionStrings__luciaconfig=mongodb://lucia-mongo:27017/luciaconfig
         - ConnectionStrings__luciatasks=mongodb://lucia-mongo:27017/luciatasks
         - ConnectionStrings__redis=lucia-redis:6379
       healthcheck:
         test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"]
         interval: 30s
         timeout: 10s
         retries: 3
       restart: unless-stopped
   
   networks:
     lucia-network:
       driver: bridge
   
   volumes:
     lucia-redis-data:
     lucia-mongo-data:
   

2. Start the stack:

   bash
   docker compose up -d
   

3. Open the Dashboard at http://localhost:7233 — the setup wizard will guide you through configuration.

🐳 Image Variants

To use voice variants, change the image in your docker-compose.yml:

yaml
# NVIDIA GPU (requires nvidia-container-toolkit)
image: seiggy/lucia-agenthost:voice

# CPU only (no GPU requirements)
image: seiggy/lucia-agenthost:voice-cpu

AMD ROCm: Not published to Docker Hub (~25GB). Build locally: docker build -t lucia:voice-rocm -f infra/docker/Dockerfile.voice-rocm .

🏠 Home Assistant Add-on (Mono-Container)

The ha-mono variant runs with no external dependencies — no Redis, no MongoDB. Uses in-memory caching and SQLite for persistence.

bash
docker run -d \
  --name lucia \
  --network host \
  -v lucia-data:/data \
  -v lucia-models:/app/models \
  lucia:ha

Volumes

Ports

⚙️ Environment Variables

Connection Strings (Standard Image)

Data Provider Configuration

Headless Setup

Skip the setup wizard by providing all required values via environment variables:

Tool Registration

Home Assistant Connection

🏗️ Architecture

Home Assistant ↔ Lucia Custom Component ↔ JSON-RPC ↔ AgentHost
                                                      ├── Orchestrator (Router → Dispatch → Aggregator)
                                                      │   ├── LightAgent
                                                      │   ├── ClimateAgent
                                                      │   ├── SceneAgent
                                                      │   ├── ListsAgent
                                                      │   └── GeneralAgent
                                                      ├── A2AHost (MusicAgent, TimerAgent)
                                                      ├── MongoDB (traces, config, tasks)
                                                      ├── Redis (session cache)
                                                      └── React Dashboard

🚢 Deployment Modes

yaml
environment:
  - Deployment__Mode=mesh

⚠️ Single-Instance Constraint: AgentHost must run as a single instance — no horizontal scaling via replicas. In-memory stores hold active alarms and timers.

Kubernetes

bash
# Using manifests
kubectl apply -f infra/kubernetes/manifests/

# Using Helm
helm install lucia infra/kubernetes/helm/lucia-helm \
  --namespace lucia --create-namespace

🏠 Home Assistant Integration

1. HACS (Recommended): HACS → Custom repositories → Add https://github.com/seiggy/lucia-dotnet → Download "Lucia" → Restart HA → Add Integration
2. Manual: Copy custom_components/lucia to your HA config → Restart → Add Integration

After installing:

1. Settings → Devices & Services → Add Integration → Lucia
2. Enter Agent Repository URL and API Key
3. Select agent in dropdown
4. Set as conversation agent under Settings → Voice Assistants → Assist

📊 Monitoring

Lucia includes OpenTelemetry instrumentation:

• Traces — Distributed tracing across orchestrator, agents, and HA API calls
• Metrics — Request rates, agent execution duration, LLM token usage
• Logs — Structured logging with correlation IDs

Export to Prometheus, Grafana, Jaeger, or any OTLP-compatible backend.

🔧 Building from Source

bash
git clone https://github.com/seiggy/lucia-dotnet.git
cd lucia-dotnet/infra/docker
docker compose up -d

Or build the image directly:

bash
docker build -t lucia:latest -f infra/docker/Dockerfile .

📄 License

MIT License — see https://github.com/seiggy/lucia-dotnet/blob/master/LICENSE.

📞 Support

• 🐛 Bug Reports: https://github.com/seiggy/lucia-dotnet/issues
• 💬 Discussions: https://github.com/seiggy/lucia-dotnet/discussions

---

Built with ❤️ for the Home Assistant community

https://github.com/seiggy/lucia-dotnet · https://github.com/seiggy/lucia-dotnet/blob/master/README.md