📑 Table of Contents

  1. What It Is

  2. Why It Exists

  3. What It Can Actually Do

  4. Before You Start

  5. Installation

  6. Setup Step by Step

  7. Prompts To Use It

  8. Commands Table

  9. Daily Workflow

  10. Tips

  11. Troubleshooting

  12. Quick Reference

🧭 What It Is

Odysseus is a self hosted AI workspace. Think of it as the ChatGPT or Claude interface, except it runs on hardware you own, with data that never leaves your machine.

It is not an LLM and not a chatbot. It is the dashboard you point at language models. You bring the model (local or API), Odysseus gives you the chat, agents, research, email, calendar, notes and document tools around it.

Built by: Felix Kjellberg (PewDiePie) Launched: May 31, 2026 License: MIT (free, open source) Link: https://github.com/pewdiepie-archdaemon/odysseus

❝

⚠️ Verify the live GitHub star count yourself before quoting it. Launch coverage reported 30,000+ stars in the first 48 hours, but that number moves fast.

💡 Why It Exists

Running local AI used to feel like a downgrade. You could host a model on your own GPU, but the moment you did, you lost everything that made the hosted products feel magic. No agents. No research mode. No memory. No clean interface. Just a raw model and a terminal.

PewDiePie's own framing of the problem: the idea that you could self host AI and skip the subscription simply was not there, and all the tools that make it useful were missing. So he started building Odysseus piece by piece, and the more capability he handed it, the more useful it got.

The deeper reason to self host: the more your model knows about you, the more useful it becomes. Odysseus lets you give it that context without handing your private data to someone else's cloud.

His line at launch: "The war on big tech has just begun."

🛠️ What It Can Actually Do

You say

What happens

"Chat with my local Llama model"

Connects to any local model or API (vLLM, llama.cpp, Ollama, OpenRouter, OpenAI), adding one is simple

"Run this whole task for me"

Agent mode plans and executes using tools: web, files, shell, skills, memory

"What model fits my GPU?"

Cookbook scans your hardware, scores model fit by VRAM, lets you download and serve with a click

"Research this topic and write it up"

Deep Research does multi step runs that gather, read and synthesize sources into a visual report

"Which model answers this best?"

Compare runs the same prompt across models blind, no bias, side by side

"Help me write this doc"

Multi tab editor (markdown, HTML, CSV) where you write and AI assists with edits and suggestions

"Remember this about me"

Persistent memory and skills via ChromaDB, the agent evolves as it learns you

"Triage my inbox"

IMAP/SMTP inbox with AI urgency reminders, auto tag, auto summary, auto reply drafts, auto spam

"Remind me and schedule tasks"

Notes, todo list and cron style scheduled tasks the agent can act on

"Sync my calendar"

Local first calendar with CalDAV sync to Radicale, Nextcloud, Apple, Fastmail

✅ Before You Start

A checklist before you install:

  • A computer you control (Linux, macOS or Windows). It also runs on mobile via Termux

  • Python 3.11+ if you do a manual install

  • Docker + Docker Compose if you want the recommended path

  • tmux on Linux/Termux (Cookbook needs it for background downloads and serves)

  • An LLM to point it at: either a local server (Ollama, vLLM, llama.cpp) or an API key (OpenAI, OpenRouter)

  • Optional: an IMAP/SMTP email account if you want the inbox features

  • Optional: a CalDAV calendar if you want calendar sync

❝

⚠️ Treat Odysseus like an admin console. It has shell access, file read/write, model downloads and API tokens. Do not expose it to the public internet without HTTPS and a trusted reverse proxy.

💻 Installation

bash

git clone <your-odysseus-repo-url>
cd odysseus
cp .env.example .env       # optional, recommended for explicit defaults
docker compose up -d --build

Compose starts Odysseus, ChromaDB, SearXNG and ntfy. The first run does a full image build. Once the containers are healthy, open http://localhost:7000.

Check it came up cleanly:

bash

docker compose ps
docker compose logs --tail=120 odysseus

🍎 Option 2: Manual install — macOS / Linux

Requirements: Python 3.11+. On Linux/Termux, Cookbook also needs tmux.

Install tmux first:

bash

# Debian/Ubuntu
sudo apt install tmux

# Arch
sudo pacman -S tmux

# Fedora
sudo dnf install tmux

Then install Odysseus:

bash

git clone <your-odysseus-repo-url>
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py            # creates data dirs, prints an initial admin password
uvicorn app:app --host 0.0.0.0 --port 7000

🪟 Option 3: Manual install — Windows (PowerShell)

powershell

git clone <your-odysseus-repo-url>
cd odysseus
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
python setup.py
uvicorn app:app --host 0.0.0.0 --port 7000
❝

⚠️ The README uses <your-odysseus-repo-url> as a placeholder. Use the real clone URL: https://github.com/pewdiepie-archdaemon/odysseus.git

🔧 Setup Step by Step

  1. Finish one of the install options above.

  2. Open http://localhost:7000 in your browser.

  3. Log in with the generated admin password (Docker prints it in logs, manual install prints it during python setup.py).

  4. Open the Settings panel (or run /setup inside the app).

  5. Point Odysseus at your LLM server, for example a local Ollama or vLLM host. Most people add providers in the app rather than editing .env.

  6. Add a search provider if you want web search (SearXNG ships bundled in Docker).

  7. Optional: connect your email account (IMAP/SMTP) for inbox triage.

  8. Optional: connect a CalDAV calendar for sync.

  9. Open Cookbook, let it scan your hardware, and pick a model that fits your VRAM.

  10. Review data/auth.json: disable open signup unless you want it, keep only your own account as admin.

❝

⚠️ Keep AUTH_ENABLED=true for any deployment reachable over a network. Only edit .env for deployment level overrides like DATABASE_URL or AUTH_ENABLED.

✍️ Prompts To Use It

Agent / task automation

Read every .md file in this folder, find any broken internal links,
and write a report of what is broken and where.
Go to my project directory, run the test suite, and summarize
which tests failed and the likely cause for each.

Deep Research

Research the current state of self hosted LLM serving in 2026.
Compare vLLM, llama.cpp and Ollama on speed, VRAM use and ease of setup.
Synthesize into a report with sources.

Compare (blind model test)

Same prompt, all my connected models, blind:
Explain the tradeoff between FP8 and AWQ quantization in two paragraphs.

Email triage

Go through my inbox from the last 24 hours. Tag anything urgent,
summarize the rest in one line each, and draft replies to the two
that clearly need a response.

Documents

Here is my rough draft. Tighten it, cut filler, keep my voice.
Show me suggestions before applying anything.

⌨️ Commands Table

Command

What it does

git clone https://github.com/pewdiepie-archdaemon/odysseus.git

Download the project

docker compose up -d --build

Build and start all services (Docker path)

docker compose ps

Check which containers are running

docker compose logs --tail=120 odysseus

View recent Odysseus logs

docker compose build --no-cache odysseus

Rebuild the image from scratch

python3 -m venv venv

Create a Python virtual environment (manual path)

pip install -r requirements.txt

Install Python dependencies

python setup.py

Create data dirs and print the initial admin password

uvicorn app:app --host 0.0.0.0 --port 7000

Start Odysseus manually

/setup

In app setup wizard

📅 Daily Workflow

A realistic day with Odysseus running on your own box:

Morning. Open http://localhost:7000. The email view has already triaged overnight mail: urgent items flagged, the rest summarized one line each, two reply drafts waiting. You approve or edit, send.

Midday. You hit a research task. Instead of opening ten tabs, you fire Deep Research with one prompt, keep working, and come back to a synthesized report with sources.

Afternoon. You hand the agent a real chore: run a script across a folder, collect the output, write up what broke. Shell, files and memory let it actually do it, not just describe it.

Evening. You draft a doc in the multi tab editor with AI suggestions on the side. Memory means it already knows your style and your projects, so the suggestions are not generic.

The point: one dashboard replaces the five or six services you were stitching together, and none of it phones home.

🧠 Tips

  • Use Cookbook before you manually download anything. It scores models against your actual VRAM, so you skip the trial and error of pulling a model that will not fit.

  • Add providers inside the app, not in .env. The README is explicit that .env is only for deployment level defaults and pre seeded secrets.

  • If you ever pasted an API key into a screenshot, demo or shared chat, rotate it. The security notes call this out directly.

  • Create a separate API token per integration and delete unused ones, rather than reusing one token everywhere.

  • For anything beyond localhost, including a Tailscale IP shared with other devices, put a TLS reverse proxy in front. Caddy auto renews Let's Encrypt certs and the config is three lines.

  • Non admin users do not get shell, Python or file read/write by default. Review each user's privileges before exposing a multi user deployment.

🩺 Troubleshooting

❝

⚠️ Cookbook model catalog prints 0

The model count check returned zero, which means the catalog did not build into the image. Rebuild without cache:

bash

docker compose build --no-cache odysseus
❝

⚠️ Browser warns "Password fields present on an insecure page"

Odysseus serves plain HTTP. That is fine on localhost, but any networked access sends your login in cleartext. Put a TLS terminating reverse proxy in front. Shortest path with Caddy:

odysseus.example.com {
  reverse_proxy localhost:7000
}
❝

⚠️ Vector memory not working in Docker

Confirm the expected startup lines appear:

bash

docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'

You want to see ChromaDB connected and MemoryVectorStore initialized. If you see DEGRADED, ChromaDB is not reachable on the expected host/port.

❝

⚠️ Lost the admin password

The initial password is generated and printed on first boot (Docker logs, or the python setup.py output on manual installs). You can also pre seed it with ODYSSEUS_ADMIN_PASSWORD in .env before first boot.

❝

⚠️ Cookbook remote server downloads fail over SSH

Cookbook uses an Odysseus owned SSH key from ./data/ssh. Add the public key to the remote server:

bash

ssh-copy-id -i data/ssh/id_ed25519.pub user@server

📌 Quick Reference

bash

# Clone
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# Docker (recommended)
cp .env.example .env
docker compose up -d --build
# open http://localhost:7000

# Health checks
docker compose ps
docker compose logs --tail=120 odysseus
docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'

# Rebuild if Cookbook catalog is empty
docker compose build --no-cache odysseus

# Manual install (macOS / Linux)
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python setup.py
uvicorn app:app --host 0.0.0.0 --port 7000

# Manual install (Windows PowerShell)
python -m venv venv; venv\Scripts\Activate.ps1
pip install -r requirements.txt
python setup.py
uvicorn app:app --host 0.0.0.0 --port 7000

By The AI Leverage - Learn and master AI daily

Keep Reading