Léo
255f7c46c1
start-macos.sh is the single-instance launcher and adopts whatever is already listening: an open ChromaDB port is a resource it reuses. With one checkout that is right. With several, it means a scratch worktree silently attaching to another checkout's vector store, and the script reports it as a success. odysseus-dev is the sibling that owns isolation instead. Ports are derived from the worktree path, so two checkouts never collide and one checkout always gets the same URL. A ChromaDB this worktree did not start is refused, never adopted — we start our own or fall closed to keyword mode and say which. The data dir, database and browser-MCP cache live under .odysseus-dev/, leaving data/ to a normal launch. A checkout wired into launchd or systemd will not boot at all, and the ports the project already means something by (7000, 7011, 7860, 8100) are refused even when asked for explicitly. Readiness is /api/ready rather than a TCP accept: the port accepting connections says nothing about the database or a writable data dir. That endpoint is not auth-exempt, so the tool owns a dev admin account, hands it to setup.py and prints it. --from-pr N fetches pull/N/head into its own worktree and boots it, borrowing a venv so a PR is a few seconds rather than a pip install. start-macos.sh is untouched: it is what the LaunchAgent runs.
A self-hosted AI workspace for chat, agents, research, documents, email, notes, calendar, and local model workflows.
Quick Start · Setup Guide · Contributing · Roadmap
Quick Start
devis the default branch and gets the newest changes first. Usemainif you want the more curated branch.
git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build
Open http://localhost:7011 when the containers are healthy. The first admin password is printed in docker compose logs odysseus.
Native installs, GPU notes, Windows/macOS instructions, HTTPS, and configuration live in the setup guide.
Features
- Chat + Agents — local/API models, tools, MCP, files, shell, skills, and memory.
- Cookbook — hardware-aware model recommendations, downloads, and serving.
- Deep Research — multi-step web research with source reading and report generation.
- Compare — blind side-by-side model testing and synthesis.
- Documents — writing-first editor with AI edits, suggestions, Markdown, HTML, CSV, and syntax highlighting.
- Email — IMAP/SMTP inbox with triage, tags, summaries, reminders, and reply drafts.
- Notes, Tasks + Calendar — reminders, todos, scheduled agent tasks, and CalDAV sync.
- Extras — gallery/image editor, themes, uploads, web search, presets, sessions, and 2FA.
Demo
A full hover-to-play tour lives on the Odysseus landing page. Its source lives under website/.
Contributing
Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, docs, and small focused refactors. See CONTRIBUTING.md and ROADMAP.md.
Security
Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model/service ports publicly.
- Keep
AUTH_ENABLED=truefor any network-accessible deployment. - Keep
LOCALHOST_BYPASS=falseoutside local development.
Deployment details are in the setup guide.
Star History
License
AGPL-3.0-or-later -- see LICENSE and ACKNOWLEDGMENTS.md.