odysseus-dev/odysseus: a self-hosted AI workspace you run with docker compose

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.

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:

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.

Editorial 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.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository