🎛️ 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 .env editing 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)

Click to expand scaling details

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 provided docker-compose.yml already includes this chroma service and wiring. All other state is multi-worker-safe natively.

🔒 Production security

Click to expand production security details & guardrails

• 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, inject DB_ENCRYPTION_KEY via an environment variable / secret manager rather than leaving it in the .env file next to the databases.
• Security headers active by default, including a strict CSP (no inline scripts) — SECURITY_HEADERS=false to disable, CONTENT_SECURITY_POLICY to customize.
• Guardrails: anti-brute-force throttle (LOGIN_MAX_FAILS/LOGIN_WINDOW_SECONDS), rate limiting (RATE_LIMIT_PER_MIN per IP + LLM_RATE_LIMIT_PER_MIN per 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)

Click to expand observability setup details

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.