Athena — Orquestrador Multi-Agente Auto-Hospedado
faelnor92/Athena
Orquestrador LLM self-hosted com UI completa, voice, código e design studios
Ver no GitHubFramework de IA multi-agente self-hosted em Python que funciona em hardware modesto com modelos locais ou APIs cloud. Oferece orquestração de agentes especializados, interface web com estúdio de escrita, integração com Home Assistant e MCP servers, além de segurança multi-usuário robusta (SSO, criptografia em repouso, auditoria).
Instalação
npx convez-ai faelnor92/Athena1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistentes de IA auto-hospedados para homelabs e infra privada
- Orquestração de múltiplos agentes com roteamento semântico e handoffs
- Estúdio de escrita com audiobooks multi-voz e revisão automática
- Integração com Home Assistant e automação residencial inteligente
- Ambientes isolados de desenvolvimento com rollback automático de código
Veredito

Projeto em desenvolvimento ativo com arquitetura robusta e features avançadas (checkpointing, isolamento de tasks, canary deployment de skills). Ideal para quem busca orquestração multi-agente escalável e auto-hospedada, mas exige experiência com infraestrutura e LLMs para aproveitar plenamente.
README
A tradução para o português deste README ainda está na fila.
🎛️ Athena — Self-Hosted Multi-Agent Assistant
Languages: Français · English (this file) · Español · Italiano · Deutsch · 中文 · 日本語
Keywords: multi-agent, ai-orchestrator, self-hosted, low-resource-llm, home-assistant, audiobook, writing-assistant, mcp-server, computer-use, docker-sandbox
[!WARNING] Active Development: This project is under active development. Expect bugs, experimental features, and potential breaking changes. Contributions, feedback, and bug reports are highly welcome!
Athena is a self-hosted AI assistant and multi-agent orchestrator built for homelabs: it runs on modest hardware with local models (or free-tier cloud APIs), and puts everything in the UI — from the first-run wizard to the last advanced setting. Web dashboard with a 3D isometric office, voice satellites (ESP32), writing studio with multi-voice audiobooks, agentic coding with automatic rollback, Home Assistant and MCP integrations — with real multi-user security (SSO, encryption at rest, quotas, audit).
📖 Read the full User Guide — available in 7 languages — to install, configure and use Athena step by step.
✨ Key Features
🧠 Orchestration & LLM Engine
- Multi-Model: OpenAI, Anthropic, Gemini, Ollama, Groq, Mistral, Qwen, any OpenAI-compatible local API.
- Provider health scheduler: rate-limited or failing providers are set aside before the call and traffic goes straight to a healthy fallback — your free-tier quotas act as one unified pool.
- Swarm: semantic routing to specialized agents (handoffs), parallel tool calls, sub-agents, inter-agent debates, optional rigid pipelines.
- Task isolation: per-run isolated state (ContextVars); parallel requests never interfere.
🛡️ Reliability & Resume
- Nothing is lost on restart: long operations (novel revision/translation, agent runs) are checkpointed and resume where they left off; a banner offers to resume interrupted work at startup.
- Transactional code edits: automatic snapshot before the Coder's edits; if tests stay broken, one-step rollback (optionally automatic).
- Skills on trial: self-generated tools are tested at creation, then run in a canary period — adopted only after repeated real successes.
- Cockpit: live provider health, run timeline with one-click replay, tokens & cost telemetry per user.
🔐 Multi-User & Security
- Authentication: password + optional 2FA (TOTP), SSO (OIDC) configurable from the UI, invite-only registration, sliding sessions with a hard cap.
- Encryption at rest (Fernet) for conversations and traces; the key stays under your control.
- Guardrails: strict CSP (no inline scripts), anti-SSRF (DNS rebinding), secret redaction in logs, anti-brute-force, rate limits (API and LLM), per-tool RBAC, audit log in the UI.
- Human-in-the-loop: sensitive actions (shell, deletions, code writes) require approval — in the UI, on Telegram, or as a push notification on your phone.
- Per-user isolation: memory, calendar, lists, briefing, budget and LLM keys are per-account; shared projects with Reader/Editor roles.
🌐 Web UI (PWA, 7 languages)
- First-run wizard: connect your AI (with a real connection test), secure access, done.
- Virtual Office (3D isometric): visualize the swarm, active agents, delegation animations.
- Everything is configurable in the UI: ~150 settings with live search, restart badges, an expert mode for the rest — no manual
.envediting needed. Interface and settings translated into 7 languages. - Built-in mini-IDE (multi-tab, live-reload) + detachable IDE window for a second screen; calendar, lists, terminal, media gallery.
- Push notifications (PWA): approvals and long-task completions on your phone, no Telegram required.
✍️ Writing Studio & Audiobook
- Novel workshop: chapter-aware revision (tracked changes), literary translation, narrative coherence check, repetition detection — as background jobs with progress and resume.
- Multi-voice audiobook 🎧: narration and dialogues are detected; each character can get their own voice (stable assignment per book). Re-running after a fix only re-synthesizes what changed (per-segment TTS cache).
- OnlyOffice integration to edit your .docx in the browser.
🧰 Tools & Extensibility
- MCP servers: plug external tools in without coding (vendored Home Assistant connector included).
- Agentic coding: git tools, code navigation, Docker-sandboxed execution, diagnostics feedback loop, parallel subtasks in isolated git worktrees, and Pull Request preparation (pushing stays human).
- On-the-fly skill creation: the AI can code its own tools — validated, self-tested and trialed before adoption.
- Computer use: LLM-optimized headless browser; SSH multi-host administration; deep web research; image/video generation; meeting transcription.
🎨 AthenaDesign Studio
- Describe what you want; Athena generates and live-previews HTML/CSS/JS, React, Mermaid diagrams, and runs Python (PPTX, charts) in a Docker sandbox.
- Design system (import your brand from CSS or a URL), annotations, WYSIWYG sliders, versions, auto-correction, PDF/PPTX/HTML export and read-only share links.
🏠 Home Automation & Automations
- Home Assistant native integration (states, actions) + room-level spatial awareness (follow-me).
- Proactive routines: per-user scheduling, habit mining ("you ask for the weather every morning → routine?"), webhook triggers, deep n8n integration.
- Daily briefing à la carte: each household member ticks what their morning digest contains — weather, agenda with traffic-aware departure times, tasks, shopping, unread emails, infrastructure, alerts.
- Notifications: Telegram, Discord, Slack, Email, Webhooks, Web Push.
💾 Memory & Learning
- RAG with citations: semantic indexing (ChromaDB); answers drawn from memory cite their sources.
- Watched knowledge folder: drop text files in, Athena learns them automatically (changed = re-learned, deleted = forgotten).
- Knowledge graph with hygiene: durable facts with re-confirmation, contradiction resolution (the most recent wins) and time decay — memory stays clean over the years.
- Experience distillation: past-task reports are periodically merged into a short list of actionable lessons.
- Backup & restore: full state in one archive.
🎙️ Voice Assistant (STT/TTS)
- 100% local: fast TTS (Kokoro or any HTTP engine, with emotional voice), optimized Whisper STT, wake word with barge-in.
- ESP32-S3 satellites: ESPHome voice satellites connect directly (no Home Assistant needed), with a YAML generator (LEDs, wake word) in the UI.
🚀 Quick Install (1-Liner)
Linux / macOS:
curl -sSL https://raw.githubusercontent.com/faelnor92/Athena/main/install.sh | bash
Windows (PowerShell):
iwr -useb https://raw.githubusercontent.com/faelnor92/Athena/main/install.ps1 | iex
- Docker Compose alternative:
docker compose up -d --build
Start: athena start or python3 server.py, then open 👉 http://localhost:8000/ — the first-run wizard takes it from there.
⚙️ Multi-worker deployment (scaling)
Shared mutable state (accounts & quotas, auth sessions, routines, invites, shared projects, per-user config) is stored in a common SQLite database in WAL mode (athena_state.sqlite3) with atomic updates — so it is consistent across multiple workers:
uvicorn server:app --host 0.0.0.0 --port 8000 --workers 4
[!NOTE] RAG in multi-worker mode. In single-process mode the vector store is embedded (local ChromaDB). For multi-worker, set
CHROMA_SERVER_HOST(+CHROMA_SERVER_PORT): all workers then talk to the same ChromaDB server (safe concurrent writes). The provideddocker-compose.ymlalready includes thischromaservice and wiring. All other state is multi-worker-safe natively.
🔒 Production security
- TLS required: put Athena behind an HTTPS reverse proxy (Caddy, Nginx, Traefik). The server automatically emits HSTS when it detects HTTPS (
X-Forwarded-Proto: https). - Encryption key outside
.env: to resist disk/backup theft, injectDB_ENCRYPTION_KEYvia an environment variable / secret manager rather than leaving it in the.envfile next to the databases. - Security headers active by default, including a strict CSP (no inline scripts) —
SECURITY_HEADERS=falseto disable,CONTENT_SECURITY_POLICYto customize. - Guardrails: anti-brute-force throttle (
LOGIN_MAX_FAILS/LOGIN_WINDOW_SECONDS), rate limiting (RATE_LIMIT_PER_MINper IP +LLM_RATE_LIMIT_PER_MINper account), sliding sessions with absolute cap (SESSION_ABSOLUTE_HOURS), password policy, audit log (Settings → Diagnostics), and admin approval of automations created by "user" accounts. - Per-tool RBAC:
ADMIN_ONLY_TOOLS="execute_bash_command,run_ssh_command,..."restricts code/command execution to admins. - Supply chain: Dependabot alerts, CodeQL analysis, blocking pip-audit (fixable CVEs) and Trivy image scan in CI; see SECURITY.md for vulnerability reporting.
- Container: the image runs as a non-root user with a
HEALTHCHECK. Install audit:bash scripts/security_scan.sh.
📡 LLM Observability (optional — OpenInference / Phoenix)
On top of the built-in cockpit (traced runs, usage, audit), Athena can export standardized LLM traces (OpenInference / OpenTelemetry) to Phoenix (Arize), a self-hostable trace viewer with evaluations. Enable:
pip install -r requirements-observability.txt # optional packages
docker compose --profile observability up -d # starts Phoenix (UI: http://localhost:6006)
then in .env: OPENINFERENCE_ENABLED=true and OTEL_EXPORTER_OTLP_ENDPOINT=http://phoenix:6006/v1/traces. Disabled by default, with zero impact.
📄 License
Distributed under the Apache 2.0 license — see LICENSE. Free to use, modify and redistribute.