Branch note: dev is the default branch and contains the latest development changes, but it may be unstable. For the more stable curated branch, use main.
Branch note: dev is the default branch and contains the latest development changes, but it may be unstable. For the more stable curated branch, use main.
A self-hosted AI workspace -- meant to be the self-hosted version of the UI experience you get from ChatGPT and Claude. But with more jank and fun. Running on your own hardware, with your own data -- local-first, privacy-first, and no trojan.
Features
Chat -- chat with any local model or API; adding them is super simple. vLLM · llama.cpp · Ollama · OpenRouter · OpenAI · GitHub Copilot
Agent -- hand it tools and let it run the whole task itself. built on opencode · MCP · web · files · shell · skills · memory
Cookbook -- Scans your hardware, recommends models, click to download and serve.. easy! built on llmfit · VRAM-aware · GGUF / FP8 / AWQ · fit scoring · vLLM / llama.cpp serving
Deep Research -- multi-step runs that gather, read, and synthesize sources into a nice visual report. adapted from Tongyi DeepResearch
Compare -- a fun tool to compare models side by side. Test completely blind, no bias! multi-model · blind test · synthesis
Documents -- YOU write the text, AI is there to assist, not the opposite. multi-tab editor · markdown · HTML · CSV · syntax highlighting · AI edits · suggestions
Memory / Skills -- Persistent memory and skills, your agent evolves over time as it better understands you and your tasks! ChromaDB · fastembed (ONNX) · vector + keyword retrieval · import/export
Email -- IMAP/SMTP inbox with AI triage built in: urgency reminders, auto-tag, auto-summary, auto-reply drafts, auto-spam. IMAP · SMTP · per-account routing · CalDAV-aware
Notes & Tasks -- Quick notes with reminders, a todo list, and scheduled tasks the agent can act on. note pings · checklist · cron-style tasks · ntfy / browser / email channels
Calendar -- Local-first calendar with CalDAV sync to Radicale / Nextcloud / Apple / Fastmail. CalDAV pull · .ics import/export · per-calendar colors · agent-aware
Works on mobile -- looks and runs great on your phone, not just desktop. responsive · installable (PWA) · touch gestures
Branch note: dev is the default branch and contains the latest development changes, but it may be unstable. For the more stable curated branch, use main.
Branch note: dev is the default branch and contains the latest development changes, but it may be unstable. For the more stable curated branch, use main.
A self-hosted AI workspace -- meant to be the self-hosted version of the UI experience you get from ChatGPT and Claude. But with more jank and fun. Running on your own hardware, with your own data -- local-first, privacy-first, and no trojan.
Features
Extras -- more to explore, happy if you give it a go! image editor · theme editor · file uploads (vision + PDF) · web search · presets · sessions · 2FA
Demo
A full, hover-to-play tour lives on the landing page (docs/index.html).
docs/index.html
Chat & Agents
Deep Research
Compare
Documents
Notes & Tasks
Quick Start
Defaults work out of the box: clone, run, then configure models/search/email inside Settings. Only edit .env for deployment-level overrides like APP_BIND, APP_PORT, AUTH_ENABLED, DATABASE_URL, or a pre-seeded admin password.
.env
APP_BIND
APP_PORT
AUTH_ENABLED
DATABASE_URL
On first setup, Odysseus creates an admin account (admin unless ODYSSEUS_ADMIN_USER is set) and prints a temporary password in the terminal. For Docker installs, the same line is in docker compose logs odysseus. Use that for the first login, then change it in Settings.
admin
ODYSSEUS_ADMIN_USER
docker compose logs odysseus
Contributing? See CONTRIBUTING.md for setup, testing, and pull request guidelines.
Docker (recommended)
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus cp .env.example .env # optional, but recommended for explicit defaults docker compose up -d --build
To include optional extras in the image (PDF viewer, Office extraction; includes AGPL PyMuPDF), build with docker compose build --build-arg INSTALL_OPTIONAL=true before up.
Open http://localhost:7000 when the containers are healthy. Docker Compose binds the web UI to 127.0.0.1 by default. If the port is taken, set APP_PORT=7001 in .env and recreate the container. Set APP_BIND=0.0.0.0 only when you intentionally want LAN/reverse-proxy access.
Requirements: Python 3.11+. Cookbook also needs tmux for background model downloads and serves. The app itself is lightweight; local model serving is the heavy part and depends on the model, runtime, GPU, and VRAM, so small hosts can connect to API or remote model servers instead. Use --host 0.0.0.0 only when you intentionally want LAN/reverse-proxy access.
tmux
--host 0.0.0.0
Apple Silicon
Docker on macOS cannot use the Metal GPU. For GPU-accelerated Cookbook on an M-series Mac, run Odysseus natively:
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus ./start-macos.sh
It launches at http://127.0.0.1:7860. To expose it to your phone over a trusted LAN/VPN such as Tailscale, bind all interfaces:
http://127.0.0.1:7860
ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh # then open http://:7860
The script also reads .env at startup, so APP_BIND=0.0.0.0 and APP_PORT set there are picked up automatically without a command-line override each run.
.env
APP_BIND=0.0.0.0
APP_PORT
Keep AUTH_ENABLED=true (the default) before binding outside loopback. Do not expose this port directly to the public internet. To build a clickable app wrapper:
AUTH_ENABLED=true
./build-macos-app.sh
Docker bundled services. Compose starts Odysseus, ChromaDB, SearXNG, and ntfy. Odysseus and the bundled service ports bind to 127.0.0.1 by default, so they are reachable from the host but not exposed to your LAN/public internet unless you opt in.
127.0.0.1
Cookbook storage in Docker. Downloads live in ./data/huggingface (~/.cache/huggingface in the container). Cookbook-installed Python CLIs and serve engines live in ./data/local (~/.local in the container), so they survive container recreation.
./data/huggingface
~/.cache/huggingface
./data/local
~/.local
Remote servers. In Cookbook -> Settings -> Servers, generate the Odysseus SSH key and add the public key to the remote server's ~/.ssh/authorized_keys. From the host you can also run:
Docker GPU overlays. CPU-only users can skip this section. Cookbook can only detect GPUs that Docker exposes to the container — if the host runtime or device passthrough is not configured, Cookbook sees the iGPU, another card, or CPU instead of your intended GPU.
For NVIDIA, scripts/check-docker-gpu.sh diagnoses GPU passthrough and can optionally install the host runtime or update .env.
scripts/check-docker-gpu.sh
.env
Read-only diagnostic (default — installs nothing, never edits .env): scripts/check-docker-gpu.sh # Print OS-specific install commands without running them: scripts/check-docker-gpu.sh --print-install-commands # Install NVIDIA Container Toolkit on Ubuntu/Debian (requires sudo): scripts/check-docker-gpu.sh --install-nvidia-toolkit # Write COMPOSE_FILE to .env (only when GPU passthrough is confirmed working): scripts/check-docker-gpu.sh --enable-nvidia-overlay # Full assisted setup — install toolkit, then enable overlay if passthrough works: scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
Safety notes:
The app never installs host GPU runtime automatically.
The app never edits .env automatically.
.env
.env is only modified when --enable-nvidia-overlay is explicitly passed, and only after GPU passthrough succeeds. --yes skips prompts but does not bypass the passthrough gate.
.env
--enable-nvidia-overlay
--yes
.env.bak.* backups created by --enable-nvidia-overlay are ignored by Git and the Docker build context.
.env.bak.*
--enable-nvidia-overlay
To enable manually without the script, add this to .env:
For NVIDIA/AMD GPU support, also read the comments in the selected overlay file: docker/gpu.nvidia.yml or docker/gpu.amd.yml.
Stack-management UIs (Portainer, Coolify, Dockhand, etc.). These tools often accept only a single Compose file and do not reliably honor COMPOSE_FILE or multiple -f overlays. CLI users should keep using the COMPOSE_FILE overlay workflow above. For stack UIs, point the stack at one of the standalone files instead, which bundle the base stack plus the GPU settings:
COMPOSE_FILE
-f
COMPOSE_FILE
docker-compose.gpu-nvidia.yml — still requires the NVIDIA Container Toolkit on the host.
docker-compose.gpu-nvidia.yml
docker-compose.gpu-amd.yml — still requires host ROCm/kfd/DRI setup, the video/render group membership, and RENDER_GID when needed.
docker-compose.gpu-amd.yml
video
render
RENDER_GID
The base docker-compose.yml plus the docker/gpu.*.yml overlays remain the source of truth; the standalone files mirror them for single-file deployments.
docker-compose.yml
docker/gpu.*.yml
Verify after enabling either overlay:
docker compose exec odysseus nvidia-smi -L # NVIDIA docker compose exec odysseus sh -lc 'test -e /dev/kfd && test -d /dev/dri && ls -l /dev/kfd /dev/dri/renderD*' # AMD
GPU passthrough ≠ llama.cpp CUDA. nvidia-smi passing inside the container confirms Docker GPU access, but llama.cpp also needs cudart and the CUDA Toolkit at runtime. If Cookbook logs show Unable to find cudart library, Could NOT find CUDAToolkit, CUDA Toolkit not found, or tensors/layers assigned to CPU, that is a Cookbook/llama.cpp build issue — not a Docker passthrough failure. Reinstall the serve engine via Cookbook → Dependencies to get a CUDA-enabled build. The same split applies to AMD/ROCm: seeing /dev/kfd and /dev/dri inside the container confirms device passthrough, not ROCm userspace or a ROCm-enabled vLLM/llama.cpp build. rocm-smi and rocminfo are not expected inside the slim Odysseus image.
GPU passthrough ≠ llama.cpp CUDA. nvidia-smi passing inside the container confirms Docker GPU access, but llama.cpp also needs cudart and the CUDA Toolkit at runtime. If Cookbook logs show Unable to find cudart library, Could NOT find CUDAToolkit, CUDA Toolkit not found, or tensors/layers assigned to CPU, that is a Cookbook/llama.cpp build issue — not a Docker passthrough failure. Reinstall the serve engine via Cookbook → Dependencies to get a CUDA-enabled build.
nvidia-smi
cudart
Unable to find cudart library
Could NOT find CUDAToolkit
CUDA Toolkit not found
The same split applies to AMD/ROCm: seeing /dev/kfd and /dev/dri inside the container confirms device passthrough, not ROCm userspace or a ROCm-enabled vLLM/llama.cpp build. rocm-smi and rocminfo are not expected inside the slim Odysseus image.
/dev/kfd
/dev/dri
rocm-smi
rocminfo
Ollama with Docker. If Ollama runs on the host, add this endpoint in Settings:
http://host.docker.internal:11434/v1
http://host.docker.internal:11434/v1
Ollama must listen outside its own loopback interface:
OLLAMA_HOST=0.0.0.0:11434 ollama serve
This connects Odysseus in Docker to an Ollama server that is already running on your host machine; it does not start Ollama inside the container. host.docker.internal is Docker's hostname for the host machine from inside the container. Cookbook Serve is a separate workflow for serving downloaded models through Odysseus/llama.cpp, so Windows users with an existing Ollama install usually only need to add the endpoint in Settings.
macOS details. start-macos.sh installs Homebrew deps, creates the venv, runs setup, and starts uvicorn on port 7860 because AirPlay often holds 7000. It uses llama.cpp/Ollama for Metal. vLLM/SGLang are CUDA/ROCm-only and do not run on macOS. MLX-only models are not served by Odysseus.
start-macos.sh
7860
7000
Native Windows
One-command launcher (creates the venv, installs deps, runs setup, starts the server; safe to re-run):
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1
If python points at an older interpreter, use py -3.12 (or another installed 3.11+ version) for the venv step.
python
py -3.12
Requirements: Python 3.11+. The core app (chat, agent, memory, documents, email, calendar, deep research) runs fully native. For full Cookbook background model downloads and the agent shell tool, also install Git for Windows (provides bash.exe). Local GPU serving of vLLM/SGLang needs Linux/WSL2; for a local model on Windows, Ollama is the easiest path — point Odysseus at http://localhost:11434/v1 in Settings.
bash.exe
http://localhost:11434/v1
Open http://localhost:7000, log in with the generated admin password, and configure everything else inside Settings.
http://localhost:7000
Troubleshooting & Advanced Setup
chromadb-client conflicts with embedded ChromaDB
chromadb-client
If chromadb-client (the lightweight HTTP-only package) is installed alongside the full chromadb package, Odysseus starts but ChromaDB silently falls back to HTTP-only mode and fails.
chromadb-client
chromadb
Fix: uninstall chromadb-client and force-reinstall the full package:
To expose Odysseus on a local network or Tailscale with HTTPS:
Change the bind address to 0.0.0.0 in .env (APP_BIND=0.0.0.0 or ODYSSEUS_HOST=0.0.0.0).
0.0.0.0
.env
APP_BIND=0.0.0.0
ODYSSEUS_HOST=0.0.0.0
Generate a locally-trusted cert for your LAN/Tailscale IPs using mkcert: mkcert -install mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip
Install the mkcert CA on any other device you want to access Odysseus from (e.g., for iOS, email the rootCA.pem to yourself, install the profile, and trust it in Certificate Trust Settings).
mkcert
rootCA.pem
Optional Dependencies
requirements-optional.txt contains packages that unlock extra features. It is not installed by default.
requirements-optional.txt
Package Feature unlocked faster-whisper Local speech-to-text (microphone -> text) via the "local" STT provider. ddgs DuckDuckGo as a search provider option. PyMuPDF PDF page rendering in the side viewer panel and form-filling. (Note: AGPL-3.0) markitdown Office/EPUB document text extraction (converts .docx/.xlsx/.pptx/.xls/.epub to Markdown).
faster-whisper
ddgs
PyMuPDF
markitdown
Outlook / Office 365 email
Chat -- chat with any local model or API; adding them is super simple. vLLM · llama.cpp · Ollama · OpenRouter · OpenAI · GitHub Copilot
Agent -- hand it tools and let it run the whole task itself. built on opencode · MCP · web · files · shell · skills · memory
Cookbook -- Scans your hardware, recommends models, click to download and serve.. easy! built on llmfit · VRAM-aware · GGUF / FP8 / AWQ · fit scoring · vLLM / llama.cpp serving
Deep Research -- multi-step runs that gather, read, and synthesize sources into a nice visual report. adapted from Tongyi DeepResearch
Compare -- a fun tool to compare models side by side. Test completely blind, no bias! multi-model · blind test · synthesis
Documents -- YOU write the text, AI is there to assist, not the opposite. multi-tab editor · markdown · HTML · CSV · syntax highlighting · AI edits · suggestions
Memory / Skills -- Persistent memory and skills, your agent evolves over time as it better understands you and your tasks! ChromaDB · fastembed (ONNX) · vector + keyword retrieval · import/export
Email -- IMAP/SMTP inbox with AI triage built in: urgency reminders, auto-tag, auto-summary, auto-reply drafts, auto-spam. IMAP · SMTP · per-account routing · CalDAV-aware
Notes & Tasks -- Quick notes with reminders, a todo list, and scheduled tasks the agent can act on. note pings · checklist · cron-style tasks · ntfy / browser / email channels
Calendar -- Local-first calendar with CalDAV sync to Radicale / Nextcloud / Apple / Fastmail. CalDAV pull · .ics import/export · per-calendar colors · agent-aware
Works on mobile -- looks and runs great on your phone, not just desktop. responsive · installable (PWA) · touch gestures
Extras -- more to explore, happy if you give it a go! image editor · theme editor · file uploads (vision + PDF) · web search · presets · sessions · 2FA
Demo
A full, hover-to-play tour lives on the landing page (docs/index.html).
docs/index.html
Chat & Agents
Deep Research
Compare
Documents
Notes & Tasks
Quick Start
Defaults work out of the box: clone, run, then configure models/search/email inside Settings. Only edit .env for deployment-level overrides like APP_BIND, APP_PORT, AUTH_ENABLED, DATABASE_URL, or a pre-seeded admin password.
.env
APP_BIND
APP_PORT
AUTH_ENABLED
DATABASE_URL
On first setup, Odysseus creates an admin account (admin unless ODYSSEUS_ADMIN_USER is set) and prints a temporary password in the terminal. For Docker installs, the same line is in docker compose logs odysseus. Use that for the first login, then change it in Settings.
admin
ODYSSEUS_ADMIN_USER
docker compose logs odysseus
Contributing? See CONTRIBUTING.md for setup, testing, and pull request guidelines.
Docker (recommended)
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus cp .env.example .env # optional, but recommended for explicit defaults docker compose up -d --build
To include optional extras in the image (PDF viewer, Office extraction; includes AGPL PyMuPDF), build with docker compose build --build-arg INSTALL_OPTIONAL=true before up.
Open http://localhost:7000 when the containers are healthy. Docker Compose binds the web UI to 127.0.0.1 by default. If the port is taken, set APP_PORT=7001 in .env and recreate the container. Set APP_BIND=0.0.0.0 only when you intentionally want LAN/reverse-proxy access.
Requirements: Python 3.11+. Cookbook also needs tmux for background model downloads and serves. The app itself is lightweight; local model serving is the heavy part and depends on the model, runtime, GPU, and VRAM, so small hosts can connect to API or remote model servers instead. Use --host 0.0.0.0 only when you intentionally want LAN/reverse-proxy access.
tmux
--host 0.0.0.0
Apple Silicon
Docker on macOS cannot use the Metal GPU. For GPU-accelerated Cookbook on an M-series Mac, run Odysseus natively:
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus ./start-macos.sh
It launches at http://127.0.0.1:7860. To expose it to your phone over a trusted LAN/VPN such as Tailscale, bind all interfaces:
http://127.0.0.1:7860
ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh # then open http://:7860
The script also reads .env at startup, so APP_BIND=0.0.0.0 and APP_PORT set there are picked up automatically without a command-line override each run.
.env
APP_BIND=0.0.0.0
APP_PORT
Keep AUTH_ENABLED=true (the default) before binding outside loopback. Do not expose this port directly to the public internet. To build a clickable app wrapper:
AUTH_ENABLED=true
./build-macos-app.sh
Docker bundled services. Compose starts Odysseus, ChromaDB, SearXNG, and ntfy. Odysseus and the bundled service ports bind to 127.0.0.1 by default, so they are reachable from the host but not exposed to your LAN/public internet unless you opt in.
127.0.0.1
Cookbook storage in Docker. Downloads live in ./data/huggingface (~/.cache/huggingface in the container). Cookbook-installed Python CLIs and serve engines live in ./data/local (~/.local in the container), so they survive container recreation.
./data/huggingface
~/.cache/huggingface
./data/local
~/.local
Remote servers. In Cookbook -> Settings -> Servers, generate the Odysseus SSH key and add the public key to the remote server's ~/.ssh/authorized_keys. From the host you can also run:
Docker GPU overlays. CPU-only users can skip this section. Cookbook can only detect GPUs that Docker exposes to the container — if the host runtime or device passthrough is not configured, Cookbook sees the iGPU, another card, or CPU instead of your intended GPU.
For NVIDIA, scripts/check-docker-gpu.sh diagnoses GPU passthrough and can optionally install the host runtime or update .env.
scripts/check-docker-gpu.sh
.env
Read-only diagnostic (default — installs nothing, never edits .env): scripts/check-docker-gpu.sh # Print OS-specific install commands without running them: scripts/check-docker-gpu.sh --print-install-commands # Install NVIDIA Container Toolkit on Ubuntu/Debian (requires sudo): scripts/check-docker-gpu.sh --install-nvidia-toolkit # Write COMPOSE_FILE to .env (only when GPU passthrough is confirmed working): scripts/check-docker-gpu.sh --enable-nvidia-overlay # Full assisted setup — install toolkit, then enable overlay if passthrough works: scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
Safety notes:
The app never installs host GPU runtime automatically.
The app never edits .env automatically.
.env
.env is only modified when --enable-nvidia-overlay is explicitly passed, and only after GPU passthrough succeeds. --yes skips prompts but does not bypass the passthrough gate.
.env
--enable-nvidia-overlay
--yes
.env.bak.* backups created by --enable-nvidia-overlay are ignored by Git and the Docker build context.
.env.bak.*
--enable-nvidia-overlay
To enable manually without the script, add this to .env:
For NVIDIA/AMD GPU support, also read the comments in the selected overlay file: docker/gpu.nvidia.yml or docker/gpu.amd.yml.
Stack-management UIs (Portainer, Coolify, Dockhand, etc.). These tools often accept only a single Compose file and do not reliably honor COMPOSE_FILE or multiple -f overlays. CLI users should keep using the COMPOSE_FILE overlay workflow above. For stack UIs, point the stack at one of the standalone files instead, which bundle the base stack plus the GPU settings:
COMPOSE_FILE
-f
COMPOSE_FILE
docker-compose.gpu-nvidia.yml — still requires the NVIDIA Container Toolkit on the host.
docker-compose.gpu-nvidia.yml
docker-compose.gpu-amd.yml — still requires host ROCm/kfd/DRI setup, the video/render group membership, and RENDER_GID when needed.
docker-compose.gpu-amd.yml
video
render
RENDER_GID
The base docker-compose.yml plus the docker/gpu.*.yml overlays remain the source of truth; the standalone files mirror them for single-file deployments.
docker-compose.yml
docker/gpu.*.yml
Verify after enabling either overlay:
docker compose exec odysseus nvidia-smi -L # NVIDIA docker compose exec odysseus sh -lc 'test -e /dev/kfd && test -d /dev/dri && ls -l /dev/kfd /dev/dri/renderD*' # AMD
GPU passthrough ≠ llama.cpp CUDA. nvidia-smi passing inside the container confirms Docker GPU access, but llama.cpp also needs cudart and the CUDA Toolkit at runtime. If Cookbook logs show Unable to find cudart library, Could NOT find CUDAToolkit, CUDA Toolkit not found, or tensors/layers assigned to CPU, that is a Cookbook/llama.cpp build issue — not a Docker passthrough failure. Reinstall the serve engine via Cookbook → Dependencies to get a CUDA-enabled build. The same split applies to AMD/ROCm: seeing /dev/kfd and /dev/dri inside the container confirms device passthrough, not ROCm userspace or a ROCm-enabled vLLM/llama.cpp build. rocm-smi and rocminfo are not expected inside the slim Odysseus image.
GPU passthrough ≠ llama.cpp CUDA. nvidia-smi passing inside the container confirms Docker GPU access, but llama.cpp also needs cudart and the CUDA Toolkit at runtime. If Cookbook logs show Unable to find cudart library, Could NOT find CUDAToolkit, CUDA Toolkit not found, or tensors/layers assigned to CPU, that is a Cookbook/llama.cpp build issue — not a Docker passthrough failure. Reinstall the serve engine via Cookbook → Dependencies to get a CUDA-enabled build.
nvidia-smi
cudart
Unable to find cudart library
Could NOT find CUDAToolkit
CUDA Toolkit not found
The same split applies to AMD/ROCm: seeing /dev/kfd and /dev/dri inside the container confirms device passthrough, not ROCm userspace or a ROCm-enabled vLLM/llama.cpp build. rocm-smi and rocminfo are not expected inside the slim Odysseus image.
/dev/kfd
/dev/dri
rocm-smi
rocminfo
Ollama with Docker. If Ollama runs on the host, add this endpoint in Settings:
http://host.docker.internal:11434/v1
http://host.docker.internal:11434/v1
Ollama must listen outside its own loopback interface:
OLLAMA_HOST=0.0.0.0:11434 ollama serve
This connects Odysseus in Docker to an Ollama server that is already running on your host machine; it does not start Ollama inside the container. host.docker.internal is Docker's hostname for the host machine from inside the container. Cookbook Serve is a separate workflow for serving downloaded models through Odysseus/llama.cpp, so Windows users with an existing Ollama install usually only need to add the endpoint in Settings.
macOS details. start-macos.sh installs Homebrew deps, creates the venv, runs setup, and starts uvicorn on port 7860 because AirPlay often holds 7000. It uses llama.cpp/Ollama for Metal. vLLM/SGLang are CUDA/ROCm-only and do not run on macOS. MLX-only models are not served by Odysseus.
start-macos.sh
7860
7000
Native Windows
One-command launcher (creates the venv, installs deps, runs setup, starts the server; safe to re-run):
git clone https://github.com/pewdiepie-archdaemon/odysseus.git cd odysseus powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1
If python points at an older interpreter, use py -3.12 (or another installed 3.11+ version) for the venv step.
python
py -3.12
Requirements: Python 3.11+. The core app (chat, agent, memory, documents, email, calendar, deep research) runs fully native. For full Cookbook background model downloads and the agent shell tool, also install Git for Windows (provides bash.exe). Local GPU serving of vLLM/SGLang needs Linux/WSL2; for a local model on Windows, Ollama is the easiest path — point Odysseus at http://localhost:11434/v1 in Settings.
bash.exe
http://localhost:11434/v1
Open http://localhost:7000, log in with the generated admin password, and configure everything else inside Settings.
http://localhost:7000
Troubleshooting & Advanced Setup
chromadb-client conflicts with embedded ChromaDB
chromadb-client
If chromadb-client (the lightweight HTTP-only package) is installed alongside the full chromadb package, Odysseus starts but ChromaDB silently falls back to HTTP-only mode and fails.
chromadb-client
chromadb
Fix: uninstall chromadb-client and force-reinstall the full package:
To expose Odysseus on a local network or Tailscale with HTTPS:
Change the bind address to 0.0.0.0 in .env (APP_BIND=0.0.0.0 or ODYSSEUS_HOST=0.0.0.0).
0.0.0.0
.env
APP_BIND=0.0.0.0
ODYSSEUS_HOST=0.0.0.0
Generate a locally-trusted cert for your LAN/Tailscale IPs using mkcert: mkcert -install mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip
Install the mkcert CA on any other device you want to access Odysseus from (e.g., for iOS, email the rootCA.pem to yourself, install the profile, and trust it in Certificate Trust Settings).
mkcert
rootCA.pem
Optional Dependencies
requirements-optional.txt contains packages that unlock extra features. It is not installed by default.
requirements-optional.txt
Package Feature unlocked faster-whisper Local speech-to-text (microphone -> text) via the "local" STT provider. ddgs DuckDuckGo as a search provider option. PyMuPDF PDF page rendering in the side viewer panel and form-filling. (Note: AGPL-3.0) markitdown Office/EPUB document text extraction (converts .docx/.xlsx/.pptx/.xls/.epub to Markdown).