Unraid guide

Install Odysseus on Unraid

Unraid users are a natural fit for Odysseus because they already run Docker, storage, and homelab services. The safest first install is a Docker Compose stack with persistent appdata and a private LAN-only web UI.

Before you start

Create a backup or snapshot before testing new AI services on a production NAS.
Decide where Odysseus app data will live, usually under /mnt/user/appdata/.
Do not expose Odysseus publicly until login, TLS, and MCP permissions are understood.
Use a small model first, then tune GPU or large model settings later.

Option A: Docker Compose on Unraid

If you use a Docker Compose plugin or manage stacks manually, clone the official repository and start from its compose setup.

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

During the first run, keep logs visible so you can capture generated admin credentials and startup errors.

Map persistent appdata

On Unraid, avoid storing app state inside disposable container layers. Map Odysseus data to an appdata path, then document that mapping before upgrades.

/mnt/user/appdata/odysseus

Open the web UI

After the service starts, open the mapped host port from a device on your LAN. The common Odysseus local port is:

http://<unraid-ip>:7000

If it fails, read the port troubleshooting guide and check Unraid Docker logs.

Connect Ollama or another model provider

If Ollama runs on the Unraid host or another LAN machine, Odysseus must use a URL reachable from inside the container. Test the provider before changing Odysseus settings.

Same Docker host: test Docker gateway or host networking behavior.
Another LAN machine: use its LAN IP and open port.
Hosted model provider: protect API keys and monitor usage.

GPU notes

If you use an NVIDIA GPU for model serving, verify GPU passthrough at the Unraid Docker level first. Odysseus itself may only need to reach the model server; the model server is the piece that needs GPU access.