v0.15 — Self-hosted • Open source

Your personal AI,
fully under your control.

humux is a self-hosted personal AI agent that runs in a single Docker container. Unified interface across messaging, email, calendars, contacts — with autonomous action, scheduled tasks, voice interaction, and persistent memory.

Quick Start Explore Features GitHub
bash — humux quickstart
git clone https://github.com/mattmezza/humux.git
Cloning into 'humux'... done.
cd humux
cp .env.example .env
cp config.yml.example config.yml
docker compose up -d
[+] Running 3/3
  ✔ Container humux Started
> Admin UI at http://localhost:8000
Quick Start

Running in under 30 seconds

One command to start. One container to manage. Your data, your infrastructure, your rules.

bash
docker run -d \
--name humux \
-p 8000:8000 \
-v ./data:/app/data \
ghcr.io/mattmezza/humux:latest
Unable to find image 'ghcr.io/mattmezza/humux:latest' locally
latest: Pulling from mattmezza/humux
Digest: sha256:humux... done
✔ Container started
> Admin UI at http://localhost:8000 — setup wizard guides you
Requires Docker. No env vars needed — setup wizard walks through LLM API key, Telegram, etc. Full guide →
Capabilities

Everything your personal AI needs

One unified interface across the tools you already use.

Messaging

Telegram with text, voice, inline approvals, and per-agent bots. WhatsApp via wacli integration.

Email

Read, compose, and manage email via Himalaya CLI. Per-agent mailboxes. Credentials resolved from vault — never in model context.

Calendar

CalDAV integration with Google Calendar, iCloud, Fastmail. Read or read-write access, bindable per agent.

Contacts

CardDAV (Purelymail, iCloud, Fastmail) and Google Contacts. Search and create contacts. Per-agent access levels.

Voice

Speech-to-text via faster-whisper. Text-to-speech via edge-tts or fully offline Kokoro 82M. Multilingual, on-device.

Memory

Two-tier memory: permanent long-term facts and expiring short-term context. Both extracted automatically from conversations.

View all features
Architecture

Python orchestrator +
battle-tested CLI tools

humux doesn't re-invent wheels. Python glues everything together while proven tools handle each protocol:

LLM Anthropic, OpenAI, Grok, Google, DeepSeek, OpenRouter
Email Himalaya CLI (Rust)
Calendar CalDAV via python-caldav
Voice faster-whisper (STT) + edge-tts / Kokoro (TTS)
Storage SQLite (4 databases)
Admin UI FastAPI + HTMX + Tailwind CSS

One container. Zero dependencies.

  • ✔ Single docker compose up to start
  • ✔ No Kubernetes, no sidecars, no external databases
  • ✔ Your API keys, your data, your infrastructure
  • ✔ Python 3.14 + uv for dependency management
  • ✔ Markdown skills — teach your agent without writing code
Open Source

Built in the open

humux is 100% open source under the MIT license. Contributions, issues, and ideas welcome. Star it on GitHub, fork it, or jump into discussions.

Star on GitHub Report an issue Read the docs