What is Odysseus
Odysseus is an open-source self-hosted AI workspace that provides a chat interface similar to ChatGPT / Claude with tools running entirely locally, keeping data on the local machine with zero privacy leakage. The tool integrates over a dozen features including chat, Agent, deep research, notes, tasks, calendar, email, and model comparison, supports multiple model backends such as vLLM, Ollama, and OpenRouter, and is a private AI hub for individuals and teams.
Main Features of Odysseus
-
AI Chat: Supports conversations with local models (vLLM, llama.cpp, Ollama) and APIs (OpenAI, OpenRouter), making it very easy to add models.
-
Agent: Autonomously completes tasks after being given tools, supports MCP, web, files, Shell, skills, and memory.
-
Cookbook Model Library: Scans hardware and recommends compatible models, one-click download and launch, supports formats such as GGUF / FP8 / AWQ.
-
Deep Research: Multi-step execution, automatically collects, reads, and synthesizes sources, and generates beautifully visualized reports.
-
Blind Model Comparison: Compares outputs from multiple models side by side, with fully anonymous voting to eliminate bias.
-
Document Editor: Multi-tab Markdown / HTML / CSV editor, with AI-assisted writing rather than AI-led writing.
-
Memory and Skills: Persistent vector memory based on ChromaDB + fastembed, allowing agents to evolve over time.
-
Email Client: Built-in IMAP/SMTP inbox, supports AI-powered smart classification, automatic summaries, automatic reply drafts, and spam filtering.
-
Notes and Tasks: Quick notes, to-do lists, scheduled tasks, supports ntfy / browser / email reminders.
-
Calendar Management: Local-first CalDAV calendar, can sync with Radicale / Nextcloud / Apple / Fastmail.
-
Mobile Support: Responsive PWA design, supports touch gestures, usable on mobile.
-
More Tools: Built-in image editor, theme editor, web search, file upload (vision + PDF), 2FA, and more.
Technical Principles of Odysseus
- Frontend Architecture: A responsive PWA interface built on a modern web technology stack, supporting a theme editor and multi-tab document editor (Markdown / HTML / CSV), enabling a native-like experience across devices through browser installation, while integrating 2FA authentication to ensure access security.
- Model Inference Layer: Connects to multiple backends through a unified abstraction layer; on the local side it supports inference engines such as vLLM, llama.cpp, and Ollama, while on the cloud side it is compatible with APIs such as OpenAI and OpenRouter, enabling unified scheduling and seamless switching among multiple models.
- Agent Execution Framework: Builds a tool-calling system based on opencode and the MCP (Model Context Protocol) standard, giving LLMs the ability to access the Shell, web, and file system, and supporting autonomous task planning, multi-step execution, and toolchain orchestration.
- Memory Retrieval System: Uses ChromaDB as the local vector database, combined with fastembed (ONNX runtime) to generate embeddings locally, supports both vector similarity retrieval and keyword retrieval modes, and enables persistent memory and import/export of skills.
- Cookbook Model Adaptation: Uses llmfit to scan hardware VRAM capacity, automatically evaluates the compatibility scores of quantization formats such as GGUF / FP8 / AWQ with the current hardware, and with one click starts a vLLM or llama.cpp background service, relying on tmux to daemonize the download and inference processes.
- Deep Research Engine: Drawing on the Tongyi DeepResearch architecture design, it implements multi-step information collection, source credibility assessment, reading extraction, and comprehensive reasoning, ultimately generating structured research reports with visual presentation.
How to use Odysseus
- Docker Deployment：
- Clone the repository to your local machine：
git clone https://github.com/pewdiepie-archdaemon/odysseus.git - Enter the project directory：
cd odysseus - Copy the environment configuration file：
cp .env.example .env - Build and start the container：
docker compose up -d --build - Access in your browser at
http://localhost:7000to enter the system. - Check the terminal or Docker logs to get the temporary administrator password and complete the first login.
- Clone the repository to your local machine：
- Apple Silicon (M series) Native Deployment：
- Clone the repository to your local machine：
git clone https://github.com/pewdiepie-archdaemon/odysseus.git - Enter the project directory：
cd odysseus - Run the startup script：
./start-macos.sh - Access in your browser at
http://127.0.0.1:7860and you can use it, with support for Metal GPU acceleration.
- Clone the repository to your local machine：
- Windows One-Click Deployment：
- Clone the repository to your local machine：
git clone https://github.com/pewdiepie-archdaemon/odysseus.git - Enter the project directory：
cd odysseus - Run the PowerShell startup script：
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1 - After completing the automatic installation following the script prompts, access the local address in your browser to use it.
- Clone the repository to your local machine：
Odysseus's Core Advantages
-
Local-first, privacy-first: All data is stored locally, with no need to upload to the cloud, completely eliminating privacy leaks and backdoor risks.
-
Ready to use out of the box: The default configuration can run, with no need for complex environment setup, and one-click deployment across multiple platforms via Docker / native / macOS App.
-
All-in-One Workspace: Integrates chat, research, notes, tasks, calendar, and email into a unified interface, reducing tool switching.
-
Open model ecosystem: Not tied to a single model, compatible with local inference and cloud APIs, and Cookbook automatically matches hardware and models.
-
Evolvable Agent: Persistent memory + a skill system make the agent understand the user better the more it is used, and it supports the MCP standard for extending tools.
Odysseus's Project Address
- Project Official Website：https://pewdiepie-archdaemon.github.io/odysseus/
- GitHub Repository：https://github.com/pewdiepie-archdaemon/odysseus
Comparison of Odysseus with Similar Competitors
| Dimension | Odysseus | Open WebUI |
|---|---|---|
| Frontend | Modern Web tech stack, PWA architecture, built-in theme editor and image editor | A modern chat interface based on Svelte, simple and aesthetically pleasing |
| Backend | Python (FastAPI / Uvicorn), modular design | Python (FastAPI), deeply integrated with Ollama |
| Vector Database | ChromaDB local persistence | No native vector library; RAG is implemented through temporary processing |
| Deployment Method | Docker / native Linux / macOS App / Windows script / PWA | Docker / native (mainly targeting Docker) |
| GPU Acceleration | Supports Metal (Apple Silicon), CUDA, and Cookbook automatically detects hardware | Relies on Ollama's underlying GPU support |
| Extension Protocol | MCP (Model Context Protocol) standard tool extension | Custom Pipelines and Functions extension |
Odysseus application scenarios
-
Personal privacy AI assistant: Safely use large models on local devices, sensitive data never leaves the machine.
-
Developer local LLM laboratory: Quickly switch, compare, and evaluate different open-source models, conduct blind tests and performance analysis.
-
Researcher in-depth investigation: Use Agents to automatically collect literature, generate structured research reports, and present them visually.
-
Team privatized knowledge base: Combine vector memory and document editing to build an internal Q&A and writing collaboration platform.
-
Personal productivity management: Integrate notes, to-dos, calendar, and email to create an AI-driven personal productivity hub.