A self-hosted, modular, local-first personal-assistant platform: an AI agent plus a growing fleet of sidecar modules (calendar, notes, tasks, mail, chat, knowledge base, storage), private and self-hosted on your own machine or server.
Status: ✅ Phases 0–3 complete, consolidated through 3.5 / 3.7 / 3.8 — the agent, LLM gateway, cross-chat memory, and web shell, plus the knowledge, storage, web-search, calendar, mail, tasks, and notes modules, module-contributed left-nav pages, and chat entity-references + attachments. First public release: v0.2.0. Next: chat bridges (Phase 4). · License: AGPL-3.0
epicurus runs on your own machine under Docker. A core service runs the agent and platform capabilities; every capability is a sidecar module the agent can use. Modules talk to the core over one standardized, local-only contract.
Full documentation lives in docs/ (and is published to the GitHub
Wiki once the wiki is enabled). Start here:
| If you want to… | Read |
|---|---|
| Install & run epicurus | User Guide → Installation |
| Configure it / manage secrets | User Guide → Configuration |
| Understand how it's built | Developer Guide → Architecture |
| Build a module | Developer Guide → Building a module |
| Look up a class or function | API Reference |
| Contribute | Contributing |
Bring up the platform's backing services (Postgres, Valkey, NATS, Qdrant, OpenBao):
git clone https://github.com/baakhoff/epicurus.git
cd epicurus
docker compose -f infra/compose/docker-compose.yml up -d # or: task infra-up…or bring up the whole platform (core, web UI, and the echo demo module) and open the shell in a browser:
docker compose up -d # or: task up
# then open http://localhost:8088/ — chat, model manager, modules, power toggleDevelop against the shared library and run the gates:
uv sync --all-packages
uv run pytest # and: ruff check . · ruff format --check . · mypy
# or simply: task checkSee the Developer Guide for the full setup.
Issues and pull requests welcome — see CONTRIBUTING.md. By contributing you agree your contributions are licensed under the AGPL-3.0.