How do I install Odysseus AI on Ubuntu with CUDA GPU support?

Install the NVIDIA driver (sudo ubuntu-drivers autoinstall), then install Ollama (curl -fsSL https://ollama.com/install.sh | sh). Ollama auto-detects CUDA and enables GPU inference. Then clone and run Odysseus AI with ./start.sh — it connects to the Ollama backend and inherits the GPU acceleration.

How do I make Odysseus AI start automatically on Linux boot?

Create a systemd user service unit file at ~/.config/systemd/user/odysseus.service pointing to the start.sh launcher. Run systemctl --user enable --now odysseus to activate it. The systemd unit file generator on this page creates the correct file for your install path.

Does Odysseus AI support AMD GPUs on Linux via ROCm?

Yes, via Ollama with ROCm backend. Install the ROCm stack from the AMD repository, then install Ollama which detects ROCm and enables GPU inference on supported RX 6000 and RX 7000 series cards. Odysseus AI itself is backend-agnostic — it talks to the OpenAI-compatible Ollama endpoint regardless of whether CUDA or ROCm is underneath.

Can I run Odysseus AI on a headless Linux server without a desktop?

Yes. Odysseus AI is a web application — the server component runs headless via the start.sh launcher, and you access the UI from any browser on the network. For production servers, pair it with nginx as a reverse proxy and a systemd service for auto-restart on crash or reboot.

Odysseus AI Linux Install — CUDA, ROCm, systemd Service (2026)

Section I

Prerequisites by distribution.

Same four things everywhere — Python 3.11+, pip, git, curl — but the package manager commands differ. Pick your distro:

# Ubuntu 22.04+, Debian 12+ sudo apt update sudo apt install -y python3.11 python3.11-venv python3-pip git curl build-essential

On Ubuntu 20.04 or Debian 11, Python 3.11 isn't in the default repo — add the deadsnakes PPA first:

sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install -y python3.11 python3.11-venv

# Fedora 39+, RHEL 9 / AlmaLinux 9 sudo dnf install -y python3.11 python3.11-devel git curl gcc gcc-c++ make

On RHEL/AlmaLinux 9, enable the EPEL repo first if Python 3.11 isn't found:

sudo dnf install -y epel-release sudo dnf install -y python3.11

# Arch Linux, Manjaro, EndeavourOS sudo pacman -Sy --noconfirm python python-pip git curl base-devel

Arch ships Python 3.12+ now — Odysseus AI works with 3.12, but if you hit dependency issues, install 3.11 from the AUR:

yay -S python311

Section II

The four-step Linux install.

These commands work on all supported distros after the prerequisites above. Run them as your regular user — not as root.

Install Ollama (for local model inference)

The official install script detects your GPU (NVIDIA CUDA, AMD ROCm, or CPU fallback) and sets up Ollama as a systemd service automatically.

curl -fsSL https://ollama.com/install.sh | sh # pull a starter model after install completes ollama pull llama3.1:8b

Skip this step if you're using cloud API providers only (OpenAI, Anthropic, etc.).

Clone the Odysseus AI repository

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

III

Run the Linux launcher

The launcher creates a Python virtual environment, installs dependencies, and starts Odysseus AI on port 7000. Save the one-time admin password it prints.

chmod +x ./start.sh ./start.sh

First run takes 2–5 minutes to install Python dependencies. Watch for "Uvicorn running on http://0.0.0.0:7000" — that's your signal it's ready.

Open the Odysseus AI workspace

From any browser on the machine:

http://localhost:7000

Log in as admin with the password from step III. In Settings → Providers, add your Ollama endpoint (http://localhost:11434/v1) or any cloud API key.

Section III

GPU acceleration — CUDA and ROCm.

Odysseus AI itself is backend-agnostic — it talks to Ollama's OpenAI-compatible endpoint regardless of whether CUDA or ROCm is underneath. The GPU setup is entirely in the Ollama layer.

NVIDIA

CUDA setup

RTX 2000 series and newer. Requires driver 525+ and CUDA Toolkit 12.

Step 1 · Install the NVIDIA driver

# Ubuntu — auto-selects correct driver sudo ubuntu-drivers autoinstall sudo reboot # verify after reboot nvidia-smi

Step 2 · Install Ollama (handles CUDA runtime)

curl -fsSL https://ollama.com/install.sh | sh # Ollama auto-detects CUDA — confirm ollama run llama3.2:3b "what GPU are you using?"

If Ollama's response mentions CUDA or the GPU name, you're accelerated. If it says CPU, the driver install didn't complete — see the diagnostic tool below.

AMD

ROCm setup

RX 6000 series (RDNA 2) and newer. Requires ROCm 6.x.

Step 1 · Install the ROCm stack

# Ubuntu 22.04 / 24.04 sudo apt install -y software-properties-common curl -fsSL https://repo.radeon.com/rocm/rocm.gpg.key | \ sudo gpg --dearmor -o /etc/apt/keyrings/rocm.gpg echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] \ https://repo.radeon.com/rocm/apt/6.0 jammy main" | \ sudo tee /etc/apt/sources.list.d/rocm.list sudo apt update sudo apt install -y rocm-hip-sdk sudo reboot

Step 2 · Add user to video group

sudo usermod -aG video $USER sudo usermod -aG render $USER # log out and back in, then verify rocm-smi

Step 3 · Install Ollama with ROCm backend

# Ollama detects ROCm automatically after install curl -fsSL https://ollama.com/install.sh | sh HSA_OVERRIDE_GFX_VERSION=11.0.0 ollama run llama3.2:3b "test"

HSA_OVERRIDE_GFX_VERSION is needed for some RX 7000 cards that aren't yet in the default ROCm whitelist. Use 10.3.0 for RX 6000 series.

Section IV

Headless server deployment.

Installing Odysseus AI on a remote Linux server with no desktop environment — a home lab box, a VPS, a rack server. The core install is identical; the difference is how you access it and keep it running.

Start the server, bind to all interfaces

By default ./start.sh binds to 0.0.0.0:7000, so it's reachable from the network immediately after launch. Run it in a persistent session so it survives your SSH disconnect:

# with tmux (recommended) tmux new -s odysseus cd ~/odysseus ./start.sh # detach with Ctrl+B then D — stays running after you close SSH

# or with screen screen -S odysseus ./start.sh # detach with Ctrl+A then D

Access from another machine

Replace localhost with your server's local IP address:

# find your server's IP hostname -I | awk '{print $1}' # then open from any browser on the same network http://<server-ip>:7000

Don't expose port 7000 raw to the internet

Odysseus AI doesn't ship HTTPS or strong rate-limiting out of the box. If your server has a public IP, put Nginx in front with TLS first — the next section covers this. Using a VPN (WireGuard, Tailscale) to reach your home server is a cleaner option than opening a firewall port.

Section V · tool

Generate a systemd unit file for Odysseus AI.

A systemd service makes Odysseus AI start at boot, restart on crash, and integrate with systemctl and journalctl. This generator creates the correct unit file for your exact install path and user.

systemd unit file generator

Fill in three fields. Copy the output to ~/.config/systemd/user/odysseus.service, then enable it with the commands shown.

Install user (your Linux username)

Full path to odysseus repo

Port

Service scope

Your odysseus.service

Enable & start commands

Section VI

Nginx reverse proxy with HTTPS.

For any deployment reachable from outside your LAN. Nginx handles TLS termination; Odysseus AI stays on localhost and never sees raw HTTPS traffic.

Install Nginx and Certbot

# Ubuntu / Debian sudo apt install -y nginx certbot python3-certbot-nginx

Create the Odysseus AI site config

sudo nano /etc/nginx/sites-available/odysseus

server { listen 80; server_name odysseus.yourdomain.com; location / { proxy_pass http://127.0.0.1:7000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300s; # needed for streaming responses } }

Enable the site and get a TLS certificate

sudo ln -s /etc/nginx/sites-available/odysseus /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx # obtain and auto-install a Let's Encrypt cert sudo certbot --nginx -d odysseus.yourdomain.com

Certbot rewrites the config to redirect HTTP to HTTPS and auto-renews the cert via a systemd timer. After this Odysseus AI is available at https://odysseus.yourdomain.com with a valid cert and no browser warnings.

Section VIII

Six common Linux install errors and fixes.

NVIDIA driver not loaded

NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver

The driver is installed but the kernel module isn't loaded — usually after a kernel update without a reboot, or a Secure Boot blockage.

sudo reboot # try this first # if still failing, check Secure Boot mokutil --sb-state # re-run driver install sudo ubuntu-drivers autoinstall sudo reboot

Python version not found

python3.11: command not found

Your distro doesn't have Python 3.11 in the default repos, or Python wasn't added to PATH after install.

# Ubuntu 20.04 — add deadsnakes PPA sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update && sudo apt install -y python3.11 python3.11-venv # Fedora sudo dnf install -y python3.11 # Verify python3.11 --version

Ollama running on CPU despite GPU present

Ollama response mentions "using CPU" or inference is < 5 tok/s

CUDA installed but Ollama can't see it. Usually the NVIDIA driver version is below 525, or Ollama was installed before the driver.

# check driver version nvidia-smi | grep "Driver Version" # if below 525, upgrade sudo ubuntu-drivers autoinstall sudo reboot # re-install Ollama after driver upgrade sudo systemctl stop ollama sudo rm /usr/local/bin/ollama curl -fsSL https://ollama.com/install.sh | sh

Port 7000 already in use

OSError: [Errno 98] Address already in use

A previous Odysseus AI process didn't exit cleanly, or another service holds 7000.

# find what holds port 7000 sudo lsof -i :7000 sudo ss -tlnp | grep :7000 # kill the PID (replace 12345) kill -9 12345 # or change the port PORT=7001 ./start.sh

AMD GPU not recognized by ROCm

No HSA agents found / GPU not in ROCm whitelist

Newer RDNA 3 cards sometimes aren't in the default ROCm whitelist. Override the GFX version.

# RX 7000 series (RDNA 3) export HSA_OVERRIDE_GFX_VERSION=11.0.0 ollama run llama3.2:3b "test" # RX 6000 series (RDNA 2) export HSA_OVERRIDE_GFX_VERSION=10.3.0 ollama run llama3.2:3b "test" # make it permanent echo 'export HSA_OVERRIDE_GFX_VERSION=11.0.0' >> ~/.bashrc

systemd service exits immediately

odysseus.service: Main process exited, code=exited, status=1

The unit file has a path or user mismatch — the most common generator mistake is a relative path instead of absolute.

# see the actual error message journalctl --user -u odysseus -n 50 # common fixes: # 1. Use absolute path in ExecStart # 2. Check WorkingDirectory exists # 3. Verify the venv path: ls ~/odysseus/.venv/bin/python systemctl --user status odysseus

Appendix

Linux install FAQ.

How do I install Odysseus AI on Ubuntu with CUDA?

Install the NVIDIA driver with sudo ubuntu-drivers autoinstall, reboot, then install Ollama via curl -fsSL https://ollama.com/install.sh | sh. Ollama auto-detects CUDA. Then clone Odysseus AI and run ./start.sh — it connects to Ollama's endpoint and inherits the GPU acceleration automatically.

Does Odysseus AI support AMD ROCm on Linux?

Yes, via Ollama with the ROCm backend. Install the AMD ROCm stack (version 6.x) from the AMD repository, add your user to the video and render groups, then install Ollama. ROCm is supported on RX 6000 series (RDNA 2) and RX 7000 series (RDNA 3). Odysseus AI itself never touches the GPU directly — it sends requests to Ollama's OpenAI-compatible API endpoint.

Can I run Odysseus AI on a headless server without a desktop?

Yes. Odysseus AI is a web application — run ./start.sh inside tmux or screen to keep it alive after SSH disconnect, or use the systemd service for proper auto-start. Access the UI from any browser at http://server-ip:7000. For internet-facing deployments, put Nginx with Certbot TLS in front.

How do I make Odysseus AI start at boot on Linux?

Use the systemd unit file generator in Section V above. It produces an odysseus.service file for ~/.config/systemd/user/ (user scope) or /etc/systemd/system/ (system scope). Enable it with systemctl --user enable --now odysseus. Check status with systemctl --user status odysseus and logs with journalctl --user -u odysseus -f.

What's the minimum GPU spec for reasonable performance?

For NVIDIA: an RTX 3060 12 GB runs 7B models at 30-50 tok/s and 13B models at 15-25 tok/s — a very comfortable experience. 8 GB VRAM (RTX 3070, RTX 4060) works for 7B models with tight headroom. Below 6 GB VRAM, 7B models often fall back to CPU partial offloading. For AMD: RX 6700 XT (12 GB) is a good entry point for RDNA 2 ROCm acceleration.

Can I run Odysseus AI on a Raspberry Pi or ARM Linux?

Technically yes — the Python backend runs on ARM64. Ollama also supports ARM64 on Linux. In practice, Raspberry Pi 4 and 5 (4-8 GB RAM) can run very small models (1B-3B) at usable speed. A Pi 5 with 8 GB runs llama3.2:3b at around 4-7 tok/s — functional but slow. Don't attempt anything above 7B on a Pi.

How do I update Odysseus AI on Linux?

Inside the project folder: git pull to fetch updates, then run ./start.sh again — it detects changes to requirements.txt and upgrades the venv. If you're running a systemd service, restart it: systemctl --user restart odysseus. Your database, uploaded files, and settings survive updates.

Should I use native install or Docker on Linux?

Native install is faster and has simpler GPU passthrough — no Container Toolkit needed, the Ollama service is already on the host. Docker makes sense if you already manage your server with compose stacks, want isolation from the host Python, or need to run multiple services with a single docker compose up. The Docker guide covers both paths.

Install Odysseus AI on Linux with GPU acceleration.