# odysseus-dev/odysseus: a self-hosted AI workspace you run with docker compose > Odysseus bundles chat, agents, research, email, notes and calendar into one self-hosted Python application. The install is four commands, the default branch is dev, and the licence is AGPL-3.0-or-later. **odysseus-dev/odysseus** — Self-hosted AI workspace. A self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar, and local model workflows. - Repository: https://github.com/odysseus-dev/odysseus - Website: https://odysseus-dev.github.io/odysseus - Stars: 87,595 · Forks: 967 - Language: Python - License: AGPL-3.0 - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/odysseus-dev-odysseus ## What odysseus-dev/odysseus actually replaces Most self-hosted AI setups end up as a pile of separate services: a chat UI, a vector store, a scheduler, an IMAP client, a CalDAV bridge, and a script that glues them together. Odysseus is an attempt to ship that pile as one application. The README describes it as "a self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar, and local model workflows," and the top-level repository layout backs that up: routes/, services/, core/, integrations/, mcp_servers/, companion/ and swift/ sit alongside a single app.py and launcher.py. The audience is narrow and specific. This is for someone who is willing to run Docker on their own hardware, point the app at a local model or an API key, and keep the whole thing behind their own authentication. It is not a hosted product and the README does not present it as one. The feature list is written for people who already know what IMAP, SMTP, CalDAV and MCP mean, and it assumes you have opinions about which of them you want in the same process as your model calls. ## How the pieces fit: routes, services, and a Chroma client The architecture visible in the repository is a fairly conventional FastAPI application. routes/ holds HTTP handlers, services/ holds the logic behind them, and core/ holds shared concerns such as auth and the database layer. app.py is the entry point. setup.py is a first-run script that creates data directories, initializes SQLAlchemy tables and sets up an initial admin user, and its docstring says it is "safe to re-run (skips what already exists)." The vector layer is split deliberately. requirements.txt installs chromadb-client, described in a comment as "the lightweight HTTP client (talks to a standalone ChromaDB service)," plus fastembed for local ONNX embeddings. That means the app expects a Chroma service somewhere rather than embedding the database in-process, and the same comment notes the app "still degrades to keyword fallback if they're ever missing." RAG, semantic memory and tool selection all sit on that path, so a missing Chroma endpoint changes behaviour rather than breaking startup. Two dependency choices are worth reading closely. The MCP pin is mcp<2, with a comment explaining that "MCP SDK v2 is a breaking rewrite, so keep fresh installs on the maintained v1 line until the servers are migrated together." And nh3 is a hard core dependency because rendered research reports are "untrusted (LLM output over crawled pages)" and report pages run under a relaxed CSP, so the HTML is allowlist-sanitized. That is a considered decision, not an accident of packaging. ## Installing odysseus with docker compose and reaching the first admin login The README's Quick Start is four commands. Note the warning attached to it: dev is the default branch and gets the newest changes first, and the README points at main if you want "the more curated branch." Clone accordingly. ```bash git clone https://github.com/odysseus-dev/odysseus.git cd odysseus cp .env.example .env docker compose up -d --build ``` The README says to open http://localhost:7000 once the containers are healthy, and that the first admin password is printed in the container logs. That is the command you run next: ```bash docker compose logs odysseus ``` Look for the generated admin password in that output, then log in and change it. If you would rather not read it from logs, setup.py has an interactive path that prompts for a username and password when run in a terminal; it lowercases the username, defaults to admin, and rejects names in RESERVED_USERNAMES. The README does not document running setup.py as part of the Docker flow, so treat the log-printed password as the supported route for that install method. There are separate compose files for GPU hosts: docker-compose.gpu-nvidia.yml and docker-compose.gpu-amd.yml. The README does not show the exact override command for either, and it defers native installs, GPU notes, Windows and macOS instructions, HTTPS and general configuration to website/setup.md. If you are not on Linux with Docker, that guide is the only place the instructions live. ## Where the default branch and the missing release tag will bite you The most concrete limitation is stated by the README itself: dev is the default branch. Cloning without a branch flag puts you on the newest code, which is also the least settled code. The README offers main as the curated alternative but does not describe what the curation process is, how far behind main lags, or how often it moves. If your deployment needs a known-good artifact, you are choosing between a moving branch and an underspecified one. There is also no retrieved release information for this repository, and the README does not document a versioned release process, a changelog, or a rollback procedure. That matters for upgrades: docker compose up -d --build rebuilds from whatever is on the branch you checked out, so an upgrade is a git pull plus a rebuild, and the README does not describe how to get back to the previous state if the rebuild produces a broken workspace. The setup.py docstring promises re-runnability for initial setup, which is not the same guarantee for a schema change between versions. Finally, the security section is blunt about the risk profile. Odysseus ships "powerful local tools," and the README's own guidance is to keep AUTH_ENABLED=true for any network-accessible deployment and keep LOCALHOST_BYPASS=false outside local development. Those two settings are the difference between a personal workspace and an open shell on your network. The repository does include SECURITY.md and THREAT_MODEL.md, which is more than many projects at this stage offer, but the README does not summarise what is in them. ## Odysseus versus stitching together Open WebUI, a scheduler and a mail client The realistic alternative is not another single product; it is assembling the same capabilities from separate self-hosted tools. A chat front end for models, a separate notes or wiki application, a CalDAV server such as Radicale, and a mail client, each with its own database and its own upgrade cycle. The difference in approach is integration versus isolation. Odysseus puts email, calendar, notes, documents and agent execution inside one FastAPI application with one database and one auth system. The README's CalDAV claim is a good illustration: requirements.txt pulls in caldav and a comment says it "handles PROPFIND discovery + REPORT fetch across Radicale, Nextcloud, Apple, Fastmail." So Odysseus is designed to sync with the calendar server you already run rather than replace it. Similarly, the MCP dependency means its agents can call external tool servers instead of only its own. That is the trade. You get one thing to install and one place where an agent can read your mail, your notes and your calendar. You also get one process whose compromise reaches all of them, one dependency tree to keep patched, and one project's release cadence governing every feature. If your organisation already separates those concerns for policy reasons, the bundled design works against you. ## Licence and the cost of staying current Odysseus is licensed AGPL-3.0-or-later, per the README and the LICENSE file, with third-party attribution in ACKNOWLEDGMENTS.md and a licenses/ directory. The practical consequence of AGPL for most readers is the network clause: if you modify the code and let users interact with it over a network, the licence's obligations attach in a way that a permissive licence would not require. That is a description of the licence text, not legal advice; if you plan to offer a modified Odysseus to other people, have a lawyer read the actual terms rather than this paragraph. The maintenance cost is the more immediate concern. The repository is not archived, but no last-push date was retrieved, so there is no basis here for claiming an update cadence either way. What can be said is structural: the dependency list is long and includes fast-moving pieces (pydantic>=2.13.4, pydantic-settings>=2.14.1, a deliberate mcp<2 pin, chromadb-client, fastembed). The MCP comment already flags a known migration debt, since the built-in servers use the v1 low-level Server decorator API and will need to move together when v2 lands. Anyone running this should expect to spend time on dependency upgrades, not just on the application's own changes. ## Conclusion Adopt Odysseus if you want one self-hosted process that already speaks IMAP, CalDAV and MCP, and you accept that the default branch is dev. Do not adopt it if you need a published release tag or a support contract, because the repository shows neither. Before you expose it beyond localhost, confirm AUTH_ENABLED=true and LOCALHOST_BYPASS=false in your .env, and read THREAT_MODEL.md, which the README links only indirectly through the setup guide's security notes. ## FAQ ### How do I install odysseus? The README's Quick Start is to clone the repository, copy .env.example to .env, and run docker compose up -d --build. Then open http://localhost:7000 once the containers are healthy. ### How do I install odysseus on Windows? The README does not give Windows steps in the Quick Start. It says native installs, GPU notes, Windows and macOS instructions, HTTPS and configuration live in the setup guide at website/setup.md, and the repository contains launch-windows.ps1, build-windows-portable.ps1 and update_windows.bat. ### How do I install odysseus on a Mac? The README defers macOS instructions to website/setup.md rather than listing them inline. The repository also contains start-macos.sh, build-macos-app.sh and an Odysseus.spec file. ### How do I use the odysseus cookbook? The README lists Cookbook as a feature and describes it as hardware-aware model recommendations, downloads, and serving. It does not document the cookbook's interface or commands, so the setup guide is the place to check. ### How do I use odysseus on mobile? The README does not document a mobile client. The repository contains a swift/ directory, but the README does not describe what it builds or how to use it from a phone. ## Sources - [Official documentation](https://odysseus-dev.github.io/odysseus) - [Official README](https://github.com/odysseus-dev/odysseus#readme) - [Project repository](https://github.com/odysseus-dev/odysseus) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/odysseus-dev-odysseus