Odysseus

Odysseus is an open-source, self-hosted AI workspace built to replicate the UI experience of ChatGPT and Claude while keeping all data on your own hardware. Licensed under MIT, it runs on Linux, macOS, and Windows via Docker or native Python, and is installable as a PWA on mobile. The project is hosted at github.com/pewdiepie-archdaemon/odysseus and, according to the repository, has accumulated over 34,000 stars since its creation in May 2026.

What It Is

Odysseus is a local-first, privacy-first AI workspace that bundles chat, autonomous agents, deep research, document editing, email, calendar, notes, and persistent memory into a single self-hosted web application. It is designed as an alternative to cloud-based AI assistants for users who want full control over their data and model choices. The core stack is FastAPI (Python) on the backend with a modular JavaScript front-end, and it uses ChromaDB for vector memory and SearXNG for web search.

Feature Set

Odysseus ships a broad set of integrated capabilities out of the box:

• Chat — connects to local models (vLLM, llama.cpp, Ollama) and remote APIs (OpenRouter, OpenAI); adding providers is done through Settings.
• Agent — built on opencode with MCP support, web, files, shell, skills, and persistent memory tools; hands off full tasks autonomously.
• Cookbook — scans hardware, recommends VRAM-appropriate models (GGUF/FP8/AWQ), and handles one-click download and serving via vLLM or llama.cpp.
• Deep Research — multi-step runs that gather, read, and synthesize sources into a visual report; adapted from Tongyi DeepResearch.
• Compare — side-by-side blind model comparison with synthesis.
• Documents — multi-tab editor supporting Markdown, HTML, and CSV with AI-assisted edits and suggestions.
• Email — IMAP/SMTP inbox with AI triage: urgency reminders, auto-tag, auto-summary, auto-reply drafts, and spam filtering; CalDAV-aware.
• Calendar — local-first calendar with CalDAV sync to Radicale, Nextcloud, Apple, and Fastmail.
• Memory / Skills — persistent vector + keyword memory via ChromaDB and fastembed (ONNX); importable and exportable.
• Notes & Tasks — quick notes with reminders, checklists, and cron-style scheduled tasks with ntfy/browser/email notification channels.
• Mobile — responsive PWA with touch gestures, installable on phones.

Architecture and Deployment

The application is structured around a FastAPI entry point (app.py) with modules for auth, database, middleware, LLM core, agent loop, agent tools, chat processing, and search. All user data lives in a local data/ directory: SQLite for sessions and messages, ChromaDB for vector memory, and flat files for settings and presets.

Docker Compose is the recommended deployment path and bundles Odysseus, ChromaDB, SearXNG, and ntfy, all bound to 127.0.0.1 by default. Native installs on Linux, macOS (including Apple Silicon with Metal GPU support via start-macos.sh), and Windows are also supported. GPU passthrough for NVIDIA (CUDA) and AMD (ROCm) is handled through optional Docker overlay files and diagnostic scripts included in the repository.

Setup Path

The quickest start is three commands:

1. git clone, cp .env.example .env, docker compose up -d --build
2. Open http://localhost:7000 and log in with the generated admin password printed in the container logs.
3. Configure models, search, and email inside Settings — no .env edits required for basic use.

Optional dependencies in requirements-optional.txt unlock local speech-to-text via faster-whisper, DuckDuckGo search, PDF rendering via PyMuPDF, and Office/EPUB document extraction via markitdown.

Security Model

The README treats Odysseus as an admin console given its shell access, file uploads, model downloads, and API token management. Key defaults include AUTH_ENABLED=true, LOCALHOST_BYPASS=false, and all bundled service ports bound to loopback. The recommended production pattern is to terminate HTTPS at a reverse proxy (Caddy, nginx, Traefik, Cloudflare Access, or Tailscale) and keep raw service ports internal-only. Non-admin users are restricted from shell, file read/write, MCP management, and app settings by default; per-user privileges are configurable.