Odysseus — Self-Hosted AI Workspace Setup Guide

Odysseus — Setup Guide

A free, self-hosted AI workspace that replaces ChatGPT and Claude. Runs on your machine, your data never leaves.

What Is Odysseus?

Odysseus is an open-source, self-hosted AI workspace created by PewDiePie. Think of it as your own private version of ChatGPT or Claude — but it runs entirely on your computer. Your conversations, documents, emails, and data stay on your machine. No subscriptions, no data harvesting, no monthly bill.

It's not just a chatbot. It's a full workspace with deep research, autonomous agents, an AI email inbox, a document editor, memory that persists across conversations, a model cookbook, and more — all running locally.

Every Feature Explained

Chat

Chat with any AI model — local or cloud. Connect to Ollama, llama.cpp, vLLM, OpenRouter, or OpenAI. Adding a new model is as simple as pasting an endpoint URL in Settings.

Agent

Hand the AI a task and let it run autonomously. It can use tools — browse the web, read/write files, run shell commands, use MCP servers — and complete multi-step tasks on its own. Built on OpenCode.

Deep Research

Give it a topic, and it searches dozens of sources, reads them, cross-references, and writes you a structured visual report. Adapted from Alibaba's Tongyi DeepResearch. Works like the Deep Research feature in ChatGPT Pro, but free.

Cookbook

This is one of the best features. Cookbook scans your hardware (CPU, GPU, VRAM) and tells you exactly which of 270+ open-source models your machine can run. It shows compatibility scores, lets you download models with one click, and can serve them locally. Supports GGUF, FP8, and AWQ formats through llama.cpp or vLLM.

Memory & Skills

Odysseus remembers you across conversations. It builds a persistent memory using vector search (ChromaDB + fastembed) so the AI gets better at understanding you and your tasks over time. You can import/export your memory. It also learns "skills" — reusable patterns for tasks you do often.

Email

Connect your email (IMAP/SMTP) and Odysseus becomes an AI email client. It triages your inbox by urgency, auto-tags messages, generates summaries, drafts replies in your writing style, and filters spam. Supports multiple accounts with per-account routing.

Documents

A multi-tab document editor where YOU write and the AI assists — not the other way around. Supports Markdown, HTML, CSV with syntax highlighting. The AI can suggest edits, rewrite sections, or help you think through what you're writing.

Compare

Test models side-by-side in a blind comparison. You send the same prompt to multiple models and evaluate responses without knowing which model wrote which — eliminating bias.

Notes & Tasks

Quick notes with reminders, a to-do list, and scheduled tasks that the agent can act on. Supports notifications through ntfy, browser push, or email.

Calendar

Local-first calendar with CalDAV sync. Works with Radicale, Nextcloud, Apple Calendar, and Fastmail. The agent is calendar-aware, so it knows your schedule.

Mobile Support

Odysseus is fully responsive and installable as a PWA (Progressive Web App). It works great on your phone — access your entire AI workspace from anywhere on your network.

Extras

Image editor, theme editor, file uploads with vision and PDF support, web search (via SearXNG), chat presets, session management, and 2FA authentication.

Prerequisites

Pick your install method and make sure you have the basics:

Docker is the easiest path. If you want GPU-accelerated local models on Apple Silicon, use the native macOS install instead (Docker on Mac can't access the Metal GPU).

Setup Option 1: Docker (Recommended)

This is the fastest way to get running. Docker handles all dependencies automatically.

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

That's it. Open http://localhost:7000 in your browser once the containers are healthy.

On first boot, Odysseus creates an admin account and prints a temporary password in the terminal. Find it with:

docker compose logs odysseus | grep password

Use that to log in, then change it in Settings.

What Docker Sets Up

Docker Compose starts four services automatically: Odysseus (the main app), ChromaDB (for memory/vector search), SearXNG (for web search), and ntfy (for notifications). Everything binds to 127.0.0.1 by default — only accessible from your machine, not your network.

Port Conflicts

If port 7000 is already in use, set a different port in .env:

APP_PORT=7001

Then recreate the container with docker compose up -d.

Setup Option 2: Native Linux / 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

Open http://localhost:7000. Log in with the temporary admin password printed in the terminal.

For Cookbook features (background model downloads), you'll also need tmux installed (sudo apt install tmux on Ubuntu or brew install tmux on macOS).

Setup Option 3: Apple Silicon (M1/M2/M3/M4)

If you have a Mac with Apple Silicon and want GPU-accelerated local models:

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

This script installs Homebrew dependencies, creates a Python virtual environment, runs setup, and starts the server. Opens at http://localhost:7860 (port 7860 because AirPlay often holds 7000).

To build a clickable macOS app:

./build-macos-app.sh

Accessing from Your Phone

To use Odysseus on your phone over your local network (or Tailscale):

ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh

Then open http://<your-mac-ip>:7860 on your phone.

Setup Option 4: Windows

One-command launcher:

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

This creates the virtual environment, installs dependencies, runs setup, and starts the server. Safe to re-run.

Or 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

Open http://localhost:7000.

For local model serving on Windows, the easiest path is Ollama. Install it, then point Odysseus at http://localhost:11434/v1 in Settings.

After Install: First Steps

1. Log In

Use the temporary admin password printed in the terminal during first boot. Change it immediately in Settings.

2. Add an AI Model

Go to Settings and add at least one model endpoint. Options:

The fastest free option: install Ollama, run ollama pull llama3.1, and add the endpoint in Odysseus Settings.

3. Try the Cookbook

Go to Cookbook. It scans your hardware and shows you which models your machine can run, ranked by compatibility. Click a model to download it, then serve it directly from Odysseus. No separate setup needed.

4. Set Up Web Search (Optional)

If you used Docker, SearXNG is already running and connected. For native installs, you can install SearXNG separately or skip this — Odysseus works fine without it, but Deep Research and web-aware agents need it.

5. Connect Email (Optional)

In Settings, add your IMAP/SMTP credentials. Odysseus will start triaging your inbox, tagging messages, generating summaries, and drafting replies in your writing style.

6. Set Up Memory

Memory works automatically — Odysseus builds a profile of you across conversations using ChromaDB. For Docker installs, ChromaDB is included. For native installs, you can either install ChromaDB separately or Odysseus will fall back to a local memory file.

GPU Setup for Local Models

NVIDIA (Docker)

Run the diagnostic script:

scripts/check-docker-gpu.sh

To install NVIDIA Container Toolkit and enable GPU passthrough:

scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay

Or manually add to .env:

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

AMD / ROCm (Docker)

scripts/check-docker-amd-gpu.sh

Then add to .env (replace 989 with your actual render group ID):

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

Apple Silicon

Use the native macOS install (./start-macos.sh). Docker on Mac cannot access the Metal GPU. Odysseus uses llama.cpp/Ollama for Metal acceleration.

Using Ollama with Docker

If Ollama is already running on your machine and Odysseus is in Docker:

1. Make sure Ollama listens on all interfaces:

   OLLAMA_HOST=0.0.0.0:11434 ollama serve
   

2. In Odysseus Settings, add this endpoint:

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

host.docker.internal is Docker's way of reaching your host machine from inside a container.

Security Notes

Odysseus has shell access, file uploads, and API token management built in. Treat it like an admin console.

• Always keep AUTH_ENABLED=true for any network-accessible deployment
• Never expose it directly to the internet without HTTPS and a reverse proxy
• Bind to 127.0.0.1 (default) unless you specifically need LAN access
• Keep .env, data/, and logs/ private — they contain your keys, conversations, and uploads
• Rotate any API keys that were ever visible in screenshots or logs

Troubleshooting

Can't find the admin password It's printed in the terminal on first boot. For Docker: docker compose logs odysseus | grep password

Port 7000 already in use Set APP_PORT=7001 in .env and restart. On macOS, AirPlay often holds port 7000 — the macOS script uses 7860 by default.

Cookbook says "no GPU detected" in Docker Docker needs explicit GPU passthrough. Run scripts/check-docker-gpu.sh to diagnose. For macOS, use the native install instead.

Models are slow Local model speed depends entirely on your hardware. If you don't have a dedicated GPU with enough VRAM, use a cloud provider (OpenRouter free tier) or a smaller model.

SearXNG / web search not working (native install) SearXNG isn't included in native installs. Either install it separately or use Docker where it's bundled.

Want to update

cd odysseus
git pull
docker compose up -d --build   # Docker
# or restart manually for native installs

Quick Reference

Links

• GitHub Repo: github.com/pewdiepie-archdaemon/odysseus
• Website: pewdiepie-archdaemon.github.io/odysseus
• Ollama (for local models): ollama.com
• OpenRouter (free cloud models): openrouter.ai
• Star the repo if this helped!