Odysseus: A Self-Hosted AI Workspace for Developers Who Want Control Over Their Tools and Data

Most developers who use AI tools regularly eventually hit the same wall: the chat interface is useful, but the workflow around it is fragmented.

A model lives in one place. Notes live somewhere else. Research is copied into a document manually. Local models require separate setup. Email, calendar, files, shell access, memory, and model comparison all sit behind different tools, accounts, or scripts. And if the work involves private code, internal documents, or personal data, sending everything to a hosted service is not always acceptable.

Odysseus is an open-source attempt to bring those pieces into one self-hosted workspace.

It is best described as a local-first alternative to the ChatGPT or Claude workspace experience: chat, agents, documents, research, memory, email, calendar, model management, and mobile access — running on hardware you control.

GitHub: https://github.com/pewdiepie-archdaemon/odysseus

Branch note: the repository’s dev branch contains the latest development changes but may be unstable. For a more curated branch, use main.

The Core Value in One Sentence

Odysseus gives developers a self-hosted AI workspace where local models, remote APIs, agents, documents, memory, research, and personal workflow tools can work together without handing all data to a hosted product.

That sentence matters because Odysseus is not just another chat UI. There are many of those already.

The interesting part is that it tries to cover the surrounding workflow developers actually deal with: choosing a model, serving it, comparing outputs, letting an agent use tools, writing documents with assistance, doing research, triaging email, managing notes, and keeping memory across sessions.

Why Another AI Workspace Matters

A typical developer AI workflow often starts clean and becomes messy quickly.

A local Ollama model may be used for private drafts. OpenAI or OpenRouter may be used for stronger reasoning. A separate web UI handles chat. Another tool handles agents. Research gets pasted into Markdown. Calendar tasks are managed elsewhere. If a local GPU is available, model serving becomes another project of its own.

None of these tools are necessarily bad. The problem is coordination.

For example:

• A developer wants to test whether a smaller local model can handle code review summaries before using a paid API.
• A researcher wants to gather sources, summarize them, and keep the result in a document without copying between several tabs.
• A team member wants an agent to work with files and shell commands, but only inside a controlled self-hosted environment.
• A privacy-conscious user wants email triage and document assistance without routing everything through a third-party SaaS workspace.
• Someone with a GPU wants model recommendations based on actual VRAM instead of guessing from Hugging Face model cards.

Odysseus is built for these kinds of workflows.

It does not promise that self-hosting removes all complexity. In fact, the project’s own description is refreshingly honest: it aims to provide a self-hosted ChatGPT/Claude-like UI experience, “but with more jank and fun.” That honesty is useful. Self-hosted AI infrastructure still has rough edges, especially around GPU drivers, model formats, and runtime compatibility.

But Odysseus tries to put those rough edges behind a coherent interface.

What Odysseus Includes

At a high level, Odysseus combines several categories of tools that are often separate in developer setups.

Chat Across Local Models and APIs

Odysseus supports chat with both local models and hosted providers.

Supported integrations include:

• vLLM
• llama.cpp
• Ollama
• OpenRouter
• OpenAI
• GitHub Copilot

This makes it useful for mixed setups. A developer can use a local model for private work, connect to OpenAI-compatible APIs when needed, or point Odysseus at an existing Ollama server.

For Docker users running Ollama on the host, the documented endpoint is:

http://host.docker.internal:11434/v1

With Ollama listening outside loopback:

OLLAMA_HOST=0.0.0.0:11434 ollama serve

That small detail is important. Many self-hosted AI tools assume users already understand Docker networking. Odysseus documents the practical path instead of leaving users to debug connection failures blindly.

Agents With Tools

The agent system is built on top of opencode and supports tool use through mechanisms such as:

• MCP
• web access
• file operations
• shell
• skills
• memory

This is where Odysseus becomes more than a chat frontend.

A chat model can answer questions. An agent with tools can inspect files, run commands, search, synthesize, and carry state across tasks. That also means the deployment needs to be treated carefully. The project is explicit about this in its security notes: Odysseus should be treated like an admin console because it can involve shell access, file uploads, model downloads, email/calendar integrations, API tokens, and local data.

That warning builds trust. A tool with shell and file access should not pretend to be harmless.

Cookbook: Hardware-Aware Model Setup

One of the more developer-focused features is Cookbook.

Instead of asking users to guess which model fits their machine, Cookbook scans the hardware and recommends models based on available resources. It supports:

• VRAM-aware recommendations
• GGUF, FP8, and AWQ model formats
• fit scoring
• vLLM and llama.cpp serving
• model download and serve workflows

This solves a very real problem.

Many developers interested in local models waste time moving between model cards, quantization notes, runtime documentation, and trial-and-error downloads. A model may technically run, but not at a useful speed. Another model may fit only with the right quantization. A third may work with llama.cpp but not with the serving path the user expected.

Cookbook does not eliminate the need to understand local inference, but it gives users a more guided starting point.

On Apple Silicon, Odysseus documents a native path because Docker on macOS cannot use the Metal GPU:

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
./start-macos.sh

That launches on:

http://127.0.0.1:7860

For Linux GPU setups, the repository includes diagnostic scripts for NVIDIA and AMD Docker passthrough rather than silently trying to modify the host. That distinction matters. The app does not automatically install GPU runtimes or edit .env; the user explicitly opts in.

Deep Research

Odysseus includes a Deep Research mode adapted from Alibaba’s Tongyi DeepResearch project.

The idea is straightforward: run multi-step research, gather and read sources, then synthesize the findings into a visual report.

This is useful for work that is too broad for a single prompt but too repetitive to do manually every time:

• comparing libraries before adopting one
• researching API changes across versions
• gathering background for technical writing
• preparing internal engineering notes
• evaluating deployment approaches

The value is not that the model “knows everything.” It is that the workflow has a structure: gather sources, process them, synthesize the result, and produce something readable.

Blind Model Comparison

The Compare feature lets users compare multiple models side by side, including blind testing.

This is more useful than it sounds.

Developers often choose models based on reputation, benchmark posts, or cost assumptions. But for a specific workflow — code explanation, bug triage, documentation cleanup, SQL generation, research summaries — the “best” model may not be obvious.

Blind comparison helps reduce bias. Instead of seeing the model name first and rationalizing the result afterward, users can judge the output directly.

For teams evaluating whether a local model is “good enough” for certain internal tasks, this can save time and reduce guesswork.

Documents: AI-Assisted Writing Without Replacing the Author

The Documents feature is described with a clear philosophy:

You write the text, AI is there to assist, not the opposite.

That is a useful framing.

Odysseus includes a multi-tab editor with support for:

• Markdown
• HTML
• CSV
• syntax highlighting
• AI edits
• suggestions

For developers, this fits common writing tasks:

• design docs
• README drafts
• release notes
• migration guides
• internal RFCs
• incident summaries
• API documentation

The important difference from a plain chat workflow is that the document remains the center of the work. The AI is not just producing text in a separate chat window that then needs to be copied, edited, and reformatted.

Memory and Skills

Odysseus includes persistent memory and skills using:

• ChromaDB
• fastembed with ONNX
• vector and keyword retrieval
• import/export

This lets the agent retain useful context over time.

For a personal self-hosted workspace, that can mean remembering preferred project conventions, recurring tasks, writing style constraints, or background information imported from previous work.

The implementation detail also matters: memory is not just a vague product claim. The project uses ChromaDB for vector storage and supports both vector and keyword retrieval, which is a practical combination. Pure vector search is not always enough for developer workflows where exact names, flags, file paths, and identifiers matter.

Email, Notes, Tasks, and Calendar

Odysseus also includes workflow tools that are not usually found in developer AI UIs:

• IMAP/SMTP email with AI triage
• urgency reminders
• auto-tagging
• summaries
• auto-reply drafts
• spam handling
• notes with reminders
• todo lists
• scheduled agent tasks
• local-first calendar
• CalDAV sync
• .ics import/export

This may look broad, but it follows the same underlying idea: an AI workspace becomes more useful when it has access to the actual work surface.

For example, an agent that can summarize an email thread, understand calendar constraints, and draft a reply is operating closer to the user’s workflow than a standalone chat box. But because these integrations involve sensitive data, self-hosting and careful access control become more important.

The project currently notes that Outlook and Microsoft 365 email accounts generally require OAuth, while Odysseus email accounts use IMAP/SMTP username-password auth. That limitation is documented rather than hidden, which is a good sign for developers evaluating the project seriously.

Mobile Support

Odysseus is responsive and installable as a PWA, with touch gestures.

This matters for self-hosted tools. Many work well on a desktop browser but become awkward on a phone. If notes, tasks, calendar, or quick chat are part of the product, mobile access is not a cosmetic feature.

For safe remote access, the documentation suggests LAN, VPN, Tailscale, HTTPS, reverse proxy, or private access layers rather than exposing the app directly to the public internet.

A Realistic Workflow Example

Consider a developer evaluating whether to run more AI work locally.

Without a tool like Odysseus, the workflow may look like this:

1. Install Ollama or llama.cpp.
2. Download a model after guessing whether it fits the machine.
3. Use one UI for chat.
4. Use another tool or terminal session for agent-style tasks.
5. Paste research into a document editor.
6. Compare outputs manually in separate tabs.
7. Store notes elsewhere.
8. Reconfigure everything again when trying a new provider.

With Odysseus, that workflow becomes more centralized:

1. Run the workspace locally.
2. Configure local or API model providers in Settings.
3. Use Cookbook to find models that fit the hardware.
4. Chat with different models from the same interface.
5. Use Compare to test models blind on real prompts.
6. Run Deep Research for multi-step source gathering and synthesis.
7. Write or refine the output in Documents.
8. Let memory and skills carry useful context forward.
9. Keep related notes, tasks, and calendar items in the same environment.

The benefit is not only fewer tabs. It is less context loss.

Developers spend a surprising amount of time moving information between tools. Odysseus reduces some of that movement by treating the AI assistant, model runtime, research process, and work artifacts as parts of one local workspace.

Quick Start With Docker

Docker is the recommended setup path.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

Then open:

http://localhost:7000

On first setup, Odysseus creates an admin account and prints a temporary password in the terminal. For Docker installs, it can also be found with:

docker compose logs odysseus

After logging in, model providers, search, email, and other integrations can be configured from Settings.

By default, Docker Compose binds the web UI to 127.0.0.1. If the port is already taken, set another port in .env:

APP_PORT=7001

Only bind to all interfaces when intentional:

APP_BIND=0.0.0.0

And keep authentication enabled for any network-accessible deployment.

Native Linux and macOS Setup

For native Linux or macOS:

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000

Requirements:

• Python 3.11+
• tmux for Cookbook background model downloads and serving

The core app is lightweight. Local model serving is the resource-heavy part and depends on the selected model, runtime, GPU, and VRAM.

For Apple Silicon, the project provides a dedicated script:

./start-macos.sh

This is the better path for GPU-accelerated local inference on M-series Macs because Docker on macOS cannot use the Metal GPU.

Native Windows Setup

Windows users can use the provided PowerShell launcher:

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

Or install manually:

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
py -3.11 -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000

For local models on Windows, Ollama is the easiest route. Configure Odysseus to use:

http://localhost:11434/v1

Full local GPU serving with vLLM or SGLang generally requires Linux or WSL2.

Security: Treat It Like an Admin Console

Odysseus is a self-hosted workspace with access to sensitive capabilities:

• shell tools
• local files
• uploaded documents
• model providers
• API tokens
• email
• calendar
• memory
• web research
• local services

The project’s security guidance is direct and worth following:

• Keep AUTH_ENABLED=true for network-accessible deployments.
• Keep LOCALHOST_BYPASS=false outside local development.
• Use SECURE_COOKIES=true when serving through HTTPS.
• Do not expose Odysseus directly to the public internet without HTTPS and a trusted proxy or private access layer.
• Keep .env, data/, logs, databases, uploads, generated media, backups, API keys, and provider tokens out of Git.
• Keep ChromaDB, SearXNG, ntfy, Ollama, vLLM, llama.cpp, and raw provider APIs internal-only.
• Expose only the authenticated Odysseus web/API entrypoint through a trusted proxy or private access layer.

This is especially important because Odysseus is not just a viewer. It can act.

That is useful, but it changes the security model.

Where Odysseus Fits Best

Odysseus is a good fit for developers who:

• want a self-hosted AI workspace instead of a hosted-only product
• use both local models and API providers
• care about keeping documents, memory, and workflow data local
• want agent tooling with files, shell, web, and MCP
• experiment with model serving and hardware-aware local inference
• prefer an integrated workspace over a collection of separate AI tools
• are comfortable managing a self-hosted application

It may not be the right fit for users who want a polished SaaS product with no setup, no infrastructure decisions, and no local security responsibility.

That tradeoff is the point. Odysseus gives more control, but control comes with operational responsibility.

A Few Implementation Details Developers Will Care About

The repository is a Python/FastAPI application with a modular frontend.

The high-level structure looks like this:

app.py                   # FastAPI entry point
core/                    # auth, database, middleware, constants
src/                     # llm_core, agent_loop, agent_tools, chat_processor, search
routes/                  # chat, session, document, memory, model endpoints
services/                # docs, memory, search, hwfit / Cookbook
static/                  # index.html, app.js, style.css, modular JS
docs/                    # landing page and preview clips

User data lives under data/, which is gitignored:

data/
  app.db
  memory.json
  presets.json
  uploads/
  personal_docs/
  chroma/
  settings.json

The project is licensed under AGPL-3.0-or-later.

That license choice is important for organizations evaluating whether to modify and deploy it. As always, review license obligations before integrating it into company infrastructure.

The Honest Appeal of Odysseus

The most convincing part of Odysseus is not that it claims to replace every AI tool. It does not need to.

Its value is more practical: it recognizes that developers do not only need a prompt box. They need a workspace where models, tools, memory, documents, research, and personal workflow data can meet — preferably under their own control.

There will be rough edges. The project says so. The dev branch may be unstable. GPU setup can still be hardware-specific. Some integrations, such as Microsoft 365 email, have known limitations.

But the direction is useful, and the feature set reflects real developer workflows rather than a thin wrapper around a chat API.

If you are exploring self-hosted AI tools, Odysseus is worth a serious look.

Try it locally, connect one model provider, run a few real tasks, and compare it against your current workflow. If it fits your needs, consider contributing installation feedback, documentation improvements, bug reports, or a focused pull request.

GitHub: https://github.com/pewdiepie-archdaemon/odysseus