Guide: Odysseus on Steam Deck / SteamOS (Docker + native + LM Studio)

[BoyMechanicus]

Installing on Steam Deck/SteamOS

All of this is to be run from inside a terminal like Konsole. Which can be launched via ctrl+alt+t

Docker (recommended)

# Cloning main for stable
git clone -b main --single-branch https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

cp .env.example .env       #I have some edits/uncomments that are needed. 
podman-compose up -d --build

Build with docker compose build --build-arg INSTALL_OPTIONAL=true before up to include optional extras(PDF viewer, Office extraction; includes AGPL PyMuPDF).

podman-compose needs to be installed(see: Installing podman-compose). I have a section for that after my example .env file. to check if you have it, run podman-compose --version and if it returns anything other than a command not found then you're good.

Starting up only needs podman-compose up -d and shutting down is also podman-compose down. Easy enough.

.env file

# Odysseus UI — Environment Configuration
# Copy this file to .env and fill in your values.

# ============================================================
# LLM Configuration
# ============================================================

# Primary LLM host (default: localhost)
LLM_HOST=localhost

# Additional LLM hosts, comma-separated (for model discovery)
# Use hostnames/IPs only; Odysseus scans common serve ports, including Ollama's 11434.
LLM_HOSTS=llm-host.local,backup-llm.local

# Optional Ollama base URL. In Docker, host Ollama is usually reachable here
# when started with OLLAMA_HOST=0.0.0.0:11434.
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# Optional LM Studio URL. In Docker, host LM Studio is reachable here
# when LM Studio is set to serve on all interfaces (0.0.0.0).
LM_STUDIO_URL=http://host.docker.internal:1234

# OpenAI API key (only needed if using OpenAI models).
# Do not commit real keys. Keep this commented until needed.
# OPENAI_API_KEY=your_openai_api_key_here

# Research service LLM endpoint
# RESEARCH_LLM_ENDPOINT=http://localhost:8000/v1/chat/completions

# Extra CA bundle for LLM providers whose TLS chain isn't in the default
# trust store. Layered ON TOP of the system / certifi bundle — verification
# stays on for every host, the trust set just gets larger. Useful for:
#   - GigaChat / Sber (Russian Trusted Root CA): without this the endpoint
#     shows offline with CERTIFICATE_VERIFY_FAILED — self-signed certificate
#     in certificate chain.
#   - On-premise / corporate LLM gateways with an internal CA.
# Point at a PEM file containing the missing root(s).
# LLM_CA_BUNDLE=/etc/odysseus/ca/extra-roots.pem

# ============================================================
# Search & Web
# ============================================================

# SearXNG instance URL (self-hosted, for web search).
# Docker Compose overrides this to http://searxng:8080 for in-network access.
SEARXNG_INSTANCE=http://localhost:8080

# Optional SearXNG cookie/CSRF secret. If blank, Docker generates one on first boot
# and stores it in the searxng-data volume.
# SEARXNG_SECRET=

# ============================================================
# Database
# ============================================================

# SQLite database path (default: sqlite:///./data/app.db)
# DATABASE_URL=sqlite:///./data/app.db

# ============================================================
# Data directory
# ============================================================
# Move everything that lives under data/ - settings, sessions, database, auth,
# cache, uploads, etc. - to another path:
# ODYSSEUS_DATA_DIR=C:\path\to\dir

# ============================================================
# Auth & Security
# ============================================================

# Enable authentication (default: true)
# AUTH_ENABLED=true

# Host bind address and port for the Odysseus web UI in Docker Compose.
# Keep APP_BIND on loopback unless you intentionally want LAN/reverse-proxy access.
APP_BIND=127.0.0.1
# Change this if another local service already uses 7000 (macOS AirPlay often does).
APP_PORT=7000

# Development-only auth bypass for loopback requests.
# Keep false for Docker, LAN, reverse proxy, and any shared deployment.
# LOCALHOST_BYPASS=false

# Mark session cookies Secure. Set true when Odysseus is served through HTTPS
# by a trusted reverse proxy or private access gateway.
# SECURE_COOKIES=true

# Optional: pre-seed the first admin password during setup.
# Do not commit a real password.
ODYSSEUS_ADMIN_PASSWORD=change_me_before_first_boot

# CORS allowed origins (default: localhost-only; restrict to your public origin in production)
# ALLOWED_ORIGINS=http://localhost:7000,http://localhost:8000

# ============================================================
# ChromaDB (vector store)
# ============================================================

# ChromaDB service host.
# Manual host run: localhost:8100 when using `docker run -p 8100:8000 chromadb/chroma`.
# Docker Compose overrides these to chromadb:8000 for in-network access.
# CHROMADB_HOST=localhost
# CHROMADB_PORT=8100

# Docker Compose host-port bind addresses for bundled services.
# Defaults are loopback-only for safety. To expose ntfy only on Tailscale,
# set NTFY_BIND to your host's Tailscale IP and update NTFY_BASE_URL.
# CHROMADB_BIND=127.0.0.1
# NTFY_BIND=127.0.0.1
# NTFY_BASE_URL=http://localhost:8091
# Example:
# NTFY_BIND=100.x.y.z
# NTFY_BASE_URL=http://100.x.y.z:8091

# ============================================================
# RAG / Embeddings
# ============================================================

# Embedding API endpoint (OpenAI-compatible /v1/embeddings)
# Default: http://{LLM_HOST}:11434/v1/embeddings (ollama)
# EMBEDDING_URL=http://localhost:11434/v1/embeddings

# Embedding API key (if there's one)
# EMBEDDING_API_KEY=embedding_api_key_here

# Embedding model name (must be available at the endpoint above)
# EMBEDDING_MODEL=all-minilm:l6-v2

# Local fallback embedding model (used when no HTTP embedding API is available)
# Uses fastembed (ONNX) — downloads model on first run (~50MB)
# FASTEMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
# FASTEMBED_CACHE_PATH=  # defaults to ~/.cache/fastembed

# ============================================================
# Misc
# ============================================================

# Cleanup interval in hours (default: 24)
# CLEANUP_INTERVAL_HOURS=24

# In-process email pollers (default: on). Set to 0 if you're driving
# polling from cron / systemd via `scripts/odysseus-mail poll-scheduled`
# and `scripts/odysseus-mail poll-summary`, otherwise both schedulers
# race on the same SQLite.
# ODYSSEUS_INPROCESS_POLLERS=1

# In-process scheduled-task runner (default: on). Set to 0 to let an
# external driver fire scheduled tasks. Calendar reminders are
# frontend-driven (polling /api/notes from the browser) so no gate is
# needed there.
# ODYSSEUS_INPROCESS_TASKS=1

# Host used by the built-in "run_script" scheduled-task action.
# Empty/local/localhost runs scripts on the app host. Set to an SSH host alias
# if you intentionally want scheduled scripts to run remotely.
# ODYSSEUS_SCRIPT_HOST=localhost

# Chat / agent attachment size cap in bytes (default: 10 MB).
# Raise this for local installs that need larger PDFs or text documents.
# Example: 52428800 = 50 MB.
# ODYSSEUS_CHAT_UPLOAD_MAX_BYTES=10485760

# Other per-feature upload size caps in bytes. All are validated and optional;
# defaults shown. An invalid value (non-integer or < 1) fails fast at startup.
# ODYSSEUS_GALLERY_UPLOAD_MAX_BYTES=104857600            # gallery image upload (100 MB)
# ODYSSEUS_GALLERY_TRANSFORM_UPLOAD_MAX_BYTES=26214400   # gallery transform input (25 MB)
# ODYSSEUS_MEMORY_IMPORT_MAX_BYTES=10485760              # memory import file (10 MB)
# ODYSSEUS_PERSONAL_UPLOAD_MAX_BYTES=26214400            # personal document upload (25 MB)
# ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=26214400       # email compose attachment (25 MB)
# ODYSSEUS_STT_MAX_AUDIO_BYTES=26214400                  # speech-to-text audio (25 MB)
# ODYSSEUS_ICS_MAX_BYTES=10485760                        # calendar .ics import (10 MB)

# ============================================================
# GPU support (Docker Compose)
# ============================================================
# Pass the host GPU into the odysseus container. Default (unset) = CPU.
# COMPOSE_FILE is a native `docker compose` feature: a colon-separated
# list of files merged left-to-right. Pick ONE GPU line below, or leave
# all commented for CPU.
#
# NVIDIA (requires nvidia-container-toolkit + `nvidia-ctk runtime
# configure --runtime=docker` on the host):
# COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml
# COMPOSE_FILE=docker-compose.yml;docker/gpu.nvidia.yml    #(Windows)
#
# AMD ROCm (requires ROCm drivers on the host and the GID of the render group):
COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
# Find the render GID with: getent group render | cut -d: -f3
RENDER_GID=989
#
# These overlays only expose the GPU devices. The slim Odysseus image
# still needs CUDA/ROCm userspace via Cookbook -> Dependencies (vLLM,
# llama-cpp-python, etc.) before models can actually serve on GPU.

This allows for defaults to be found when adding models. And allows for easier scanning. If you have something like ollama or lmstudio running locally alpaca will connect to it via host.docker.internal

This also exposes the GPU to Odysseus.

Here's what this env file does.

• Exposes the GPU to Odysseus.
• Keeps the UI bound to 127.0.0.1:7000 by default; expose via reverse proxy or port mapping only if you choose to.
• Tells Odysseus where to look for models(Ollama/LM Studio via host.docker.internal).
• sets a default password you'll change on first login.
• sets searxng url

Installing podman-compose

There's a few ways to do this. uv, ### pip && venv, installing uv from inside venv. In order of ease of use to

uv

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install podman-compose

And now we have podman-compose installed and can run it without a virtual environment(venv). If for some reason uv is not found, export PATH="$HOME/.local/bin:$PATH" will append to path.

And now we have podman-compose installed and can run it without a virtual environment(venv). Also if you already have a virtual environment in another directory, you can use this without rm -rf.

pip && venv

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install podman-compose

Note: This only works when venv exists and is activated.

old method to install with uv in an venv

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install uv
uv pip install podman-compose
#uv tool install podman-compose
rm -rf venv

If you have an existing venv somewhere else you can skip the rm -rf and just activate your venv and install uv and then podman-compose.

Native Linux / macOS

Not only should you run everything here in a terminal. You can benefit from running this inside a tmux session. Namely because you can detach the session and come back to it later if you need to troubleshoot or check logs.

#git clone -b feature-branch --single-branch https://github.com
# Cloning main for stable
git clone -b main --single-branch https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

# We're adding node for MCP
# this makes node isolated to Odysseus, and not a system-wide install. 
wget https://nodejs.org/download/release/v20.11.1/node-v20.11.1-linux-x64.tar.xz
tar -xJf node-v20.11.1-linux-x64.tar.xz
export PATH="$PWD/node-v20.11.1-linux-x64/bin:$PATH"

# venv
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip

# install and setup
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000

Shutting down the native install is a ctrl+c away.

Installing this way comes with fewer features from my experience. I've tried both native and docker.

I added nodejs here this way because installing in steamOS requires disabling readonly and that means it vanishes each time steamOS is updated. I also updated pip. Not much else to say here. Your results may vary.

Setting LM Studio to work with Odysseus

Here are some notes on setting LM Studio to work with Odysseus.

Note

The URL for LM Studio on your host may look like 127.0.0.1 or localhost, but to Odysseus it's actually http://host.docker.internal:1234. This is because Docker maps the SteamOS host back into the container via extra_hosts.

Note

If Odysseus is installed natively, localhost is fine.
If Odysseus is in Docker/Podman, localhost means “inside the container,” so use http://host.docker.internal:1234 for LM Studio instead.

1. Install the Flatpak and launch it.
2. Download some models.
3. In the Developer tab, click Server Settings.

   • Click Require Authentication.

   • Click Manage Tokens, create a new token, give it a name, use the default settings, and copy the key. You'll paste it into Odysseus.

     [!TIP]
     Be careful here. You'll only see this key once. But if you forget it, you can make another.

   • Enable Serve on Local Network.

   • LM Studio uses 1234 by default, so make sure you remember which port you are using.

   • In Odysseus, go to Settings > Add Models > LOCAL and paste the key into the API key field.

   • When adding the server, make sure the URL matches the LM Studio port, for example: http://host.docker.internal:1234/v1.

Congratulations. You're ready to start using Odysseus + LM Studio.