Odysseus

Odysseus: A Self-Hosted AI Workspace for Privacy-First, Local-First AI

[Odysseus image: ]

In a world where AI tools often ride on cloud services, Odysseus offers a bold promise: a self-hosted AI workspace that brings the familiar UI and capabilities you expect from modern assistants, but running entirely on your own hardware with your data. It’s designed to be privacy-first, local-first, and delightfully hands-on—what you get is not just an app, but a complete, sandboxed environment you control end-to-end. It’s built to be janky and fun in the right ways, with a focus on reliability and extensibility.

What Odysseus Is

Odysseus is a self-hosted AI workspace that strives to replicate the UX of contemporary AI chat interfaces, while giving you the freedom and security of operating on your own machine. It’s not just a chat panel; it’s a multi-tool platform that blends conversational AI with practical workflow features. The project emphasizes local model support, privacy, and a pluggable architecture that can connect to various backends and services. If you’re used to cloud-based copilots, Odysseus aims to give you that same feel—minus data leakage risk, with more control over models, memory, and tools.

Key Concepts

• Local-first, privacy-first design: Data stays on your machine; you decide how models are provisioned and how information flows.
• Pluggable AI stack: Chat with multiple local models or remote APIs; swap out providers without losing your workflow.
• Tool-empowered agents: Agents can be entrusted with workflows and tools, not just chat responses.
• Cookbook and memory: The system analyzes your hardware and usage to suggest models and optimize serving; memory and skills evolve with you.
• Documents and notes: AI-assisted editing, summarization, and task management that tie into your daily work.

The Hero Image sets the tone: Odysseus as a self-contained AI workspace you can run in your own environment, with a playful, practical edge.

Core Features Explained

Chat

• Multimodel support: Chat with any local model or API, with straightforward ways to add new providers.
• Examples of supported backends: vLLM, llama.cpp, Ollama, OpenRouter, OpenAI, and even GitHub Copilot-style integrations.
• Local privacy: Conversations remain in your environment, not in a remote cloud.

Agent

• Autonomous task execution: Give agents tools and let them carry out tasks end-to-end.
• Tooling and memory: Connects to memory systems and a suite of tools to perform multi-step tasks.

Cookbook

• Auto-recommendations: Scans your hardware and suggests suitable models; one-click download and serve.
• VRAM-aware serving: Optimizes for available GPU memory and hardware constraints.
• Presets and formats: Works with GGUF, FP8, AWQ, and related serving formats.

Deep Research

• Multi-step synthesis: Runs multi-stage processes to gather, read, and synthesize sources into visual reports.
• Based on Tongyi DeepResearch lineage: Evolved into a practical research-orientation to collect and present sources.

Compare

• Side-by-side model comparisons: A blind, unbiased evaluation that reduces testing bias.
• Multimodel and synthesis: Compare multiple models on the same criteria to inform selection.

Documents

• AI-assisted writing: The user writes the content, AI assists rather than dominates.
• Rich editor features: Multi-tab editor with Markdown, HTML, CSV; syntax highlighting; AI edits and suggestions.

Memory / Skills

• Persistent memory: The agent evolves over time, learning user preferences, tasks, and workflows.
• Vector memory: ChromaDB-backed, fast embeddings, and keyword retrieval with import/export options.

Email

• AI triage-enabled inbox: IMAP/SMTP, with auto-tagging, auto-summarization, auto-replies, and spam filtering.
• Per-account routing and CalDAV awareness for calendar integration.

Notes & Tasks

• Quick notes with reminders and a to-do list.
• Task scheduling and “agent-aware” tasks that the agent can act on.

Calendar

• Local-first calendar with CalDAV sync to Radicale, Nextcloud, Apple, or Fastmail.
• ICS import/export, per-calendar colors, and agent awareness.

Mobile Support

• Odysseys designed to feel and run well on mobile devices too, not just desktops.
• Responsive, installable as a PWA, with touch gestures.

Extras

• Image editor, theme editor, file uploads (vision + PDF), web search, presets, and sessions.
• Two-factor authentication (2FA) support for added security.

Demo Tour: What You’ll See

A full, hover-to-play tour lives on the landing page (docs/index.html). The tour showcases key capabilities:

• Chat & Agents: A dynamic demo of a chat with agent tools in action.
• Deep Research: A guided example of collecting sources and producing a synthesized report.
• Compare: A vivid side-by-side model comparison.
• Documents: A quick walkthrough of AI-assisted editing in documents.
• Notes & Tasks: A glance at a smart notes system that drives to-do items and reminders.

Supporting visuals you’ll encounter include:

• Chat & Agents image:
• Deep Research image:
• Compare image:
• Documents image:
• Notes & Tasks image:

Quick Start: Getting Odysseus Running

Defaults work out of the box: clone, run, then configure models/search/email inside Settings. The first boot prints a temporary admin password in the terminal (unless ODYSSEUSADMINUSER is set). For Docker installations, the same initial password appears in docker compose logs.

Docker (recommended)

• What you’ll typically run:
• Commands to start:
• Open the UI at http://localhost:7000 when healthy.
• Docker Compose ports are bound to 127.0.0.1 by default; to expose on LAN, adjust APPPORT and APPBIND in .env.

Code snippet (typical flow):

• git clone https://github.com/pewdiepie-archdaemon/odysseus.git
• cd odysseus
• cp .env.example .env
• docker compose up -d --build
• Access http://localhost:7000 after health checks

Native Linux / macOS

• A local path for Python dependencies and serving:
• Commands:
• Requires Python 3.11+
• Cookbook also needs tmux for background downloads.

Apple Silicon (Mac)

• Native GPU acceleration path when Metal isn’t available in Docker:
• Start up with:
• For exposure to a phone on LAN or VPN (e.g., Tailscale), bind all interfaces:
• Ensure APPBIND and APPPORT values propagate from .env at startup.

Windows (Native, with a single launcher)

• One-command launcher (PowerShell):
• Or manual steps to set up a venv, install dependencies, run UVicorn.

Notes on GPU and hardware

• Docker GPU overlays: How to diagnose and enable NVIDIA or AMD GPUs behind Docker.
• Important caveats:
• Docker GPU passthrough is not the same as CUDA runtime inside the container. If you see missing cudart or CUDA Toolkit errors, you may need to reinstall the serve engine (Cookbook → Dependencies).
• AMD/ROCm paths require manual editing of .env and proper GPU overlays.

Ollama with Docker

• If you run Ollama on the host, Odysseus can connect to it via an endpoint like http://host.docker.internal:11434/v1. Ollama must listen on an interface accessible to the Docker container.

Troubleshooting & Advanced Setup

• If chromadb-client conflicts with embedded ChromaDB, uninstall chromadb-client and reinstall chromadb.
• For HTTPS exposure on LAN/Tailscale:
• Set APP_BIND=0.0.0.0
• Use mkcert to generate locally trusted certs
• Run UVicorn with ssl-certfile and ssl-keyfile
• Trust the local CA on devices you want to access Odysseus from
• Optional dependencies (requirement-optional.txt) unlock extra features, including local speech-to-text, DuckDuckGo search, PDF rendering, and Office/EPUB text extraction.

Security and Access Control

Odysseus is a powerful, self-hosted workspace. Treat it like an admin console:

• AUTH_ENABLED should be true for network-accessible deployments.
• LOCALHOST_BYPASS should be false in shared or network deployments.
• SECURE_COOKIES should be true when serving through HTTPS via a trusted proxy.
• Do not expose the app directly to the public internet without HTTPS and a trusted access layer.
• Keep sensitive files and tokens out of Git and private shares.
• Review user privileges carefully; non-admin users should have limited access.
• Rotate API keys and tokens that have been exposed in shared logs or chats.
• Use a private access layer (Cloudflare Access, Nginx, Caddy, Traefik, etc.) to isolate the ODYSSEUS web/API entrypoint.

Private or Proxied Deployments

Odysseus binds to 127.0.0.1 by default; production/private setups commonly place the app behind a reverse proxy with HTTPS:

• 127.0.0.1:7000 on the private side
• HTTPS termination at a trusted reverse proxy
• Private access gateway in front of the app
• Internal service ports stay internal (0.0.0.0 exposure is optional and should be deliberate)

Common internal ports you’ll encounter:

• 7000: Odysseus app
• 8080: SearXNG
• 8091: ntfy
• 8100: ChromaDB host
• 11434: Ollama
• 8000-8020: Local model/provider APIs

Configuration and Architecture

Odysseus is designed to be configurable and modular:

• Core app: FastAPI-based entry point
• Modules: Auth, database, middleware, models, agent loop, chat processing, memory, documents, email, calendar, and more
• Tools: A suite of sub-services including docs, memory, search, and cookbook
• Front-end: Static assets, index.html, app.js, style.css plus modular front-end components

Data storage

• All user data lives under data/ (gitignored): app.db, memory.json, presets.json, uploads/, personal_docs/, chroma/, settings.json
• This makes backups, migrations, and privacy controls straightforward

Architectural sketch (high level)

• app.py: FastAPI entry
• core/: authentication, database, middleware
• src/: LLM core, agent loop, tools, chat processor, search
• routes/: chat, session, document, memory, model endpoints
• services/: docs, memory, search, hwfit (Cookbook)
• static/: UI bundle
• docs/: landing page, previews, clips

Images from Input to Visualize Key Moments

• Odysseus hero:
• Chat & Agents tour:
• Deep Research tour:
• Compare tour:
• Documents tour:
• Notes & Tasks tour:
• Star history badge (engagement trend): (image included via link in input)
• Star History Chart: https://api.star-history.com/chart?repos=pewdiepie-archdaemon/odysseus&type=date&legend=top-left
• Link to full history: https://www.star-history.com/?repos=pewdiepie-archdaemon%2Fodysseus&type=date&legend=top-left

Developer and Community Notes

Contributing

Odysseus welcomes contributions. The most helpful routes are fresh-install testing, provider setup bugs, mobile/editor polish, docs, and small, focused refactors. See ROADMAP.md for the current help-wanted list. If you’d like to contribute:

• Clone the repository and run in a clean environment
• Follow the setup instructions in CONTRIBUTING.md
• Run tests and document any edge cases or compatibility notes
• Propose changes via a PR and engage with maintainers respectfully

What You’ll Find in the Documentation

• Setup and quick start (Docker and native paths)
• GPU and driver compatibility notes (NVIDIA and AMD)
• Advanced GPU overlays and how to enable them safely
• Security guidance for private deployments
• Detailed configuration variables and their effects
• Troubleshooting steps for common issues
• Architecture and data flow diagrams (textual descriptions here; visuals live in docs)

A Note on Licensing and Credits

Odysseus is released under the MIT license. The project acknowledges third-party components and inspirations (including references to Tongyi DeepResearch lineage and related open-source projects). See LICENSE and ACKNOWLEDGMENTS.md for full details.

The Vision, in Practice

Odysseus isn’t merely a set of features; it’s a philosophy about AI tooling: you should be able to run sophisticated AI workflows on hardware you control, with data that you own, without surrendering your privacy, and with the freedom to tailor tools to your exact needs. It’s about turning an AI workspace into a dependable partner that respects boundaries, scales with your hardware, and evolves with your tasks.

If you’re curious about how it feels in practice, the demo visuals on the landing page illustrate the experience:

• Chat & Agents: a practical conversation with an agent that can take actions
• Deep Research: a structured research workflow that aggregates, reads, and synthesizes sources
• Compare: a fair, side-by-side model comparison
• Documents: a realistic editing and markup experience
• Notes & Tasks: a living task space that strings notes to actions

Ready to embark? The journey begins with a clone, a setup, and a careful read of the configuration options. You’ll see that Odysseus is not just a tool; it’s a workspace designed to be personalized, private, and powerful—an AI assistant built to respect you as its operator and partner.

Star History Insight: A Quick Pulse

For those who like to watch adoption and activity trends, Odysseus has a star history pulse you can glance at to gauge community engagement over time. The chart tracks stars by date, painting a picture of growth and interest. It sits alongside the main repository to remind readers that this is a living project, nourished by its community.

Closing Thoughts

Odysseus invites you to try a different model of AI tooling—one that keeps your data in your control, one that respects your privacy, and one that supports a broad suite of workflows from chat to email to calendar to document editing. It’s not a “perfect” product out of the box; it’s a platform ripe for exploration, customization, and collaboration. Whether you’re a hobbyist tinkering on a personal server, a researcher aggregating sources locally, or a team aiming to deploy a secure, private AI workspace, Odysseus offers a pathway to a robust, self-hosted AI future.

If you want to dive deeper, explore the built-in tutorials, the quick-start instructions, and the elaborate configuration options described in the docs. The project’s design choices emphasize safety, modularity, and a playful spirit—an invitation to build your own Odysseus, tailored to your hardware, your data, and your ambitions.