seiggy/lucia-agenthost repository overview

⁠Lucia — Autonomous Home Assistant AI

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

• Docker⁠ 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:

   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:
   

   Copy

2. Start the stack:

   docker compose up -d
   

   Copy

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:

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

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

⁠🏠 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.

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

environment:
  - Deployment__Mode=mesh

⁠Kubernetes

# 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

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

Or build the image directly:

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

⁠📄 License

MIT License — see LICENSE⁠.

⁠📞 Support

• 🐛 Bug Reports: GitHub Issues⁠
• 💬 Discussions: GitHub Discussions⁠

Built with ❤️ for the Home Assistant community

GitHub Repository⁠ · Full Documentation⁠