macOS guide

Install Odysseus on macOS Apple Silicon

For Apple Silicon Macs, the most comfortable path is usually native Odysseus plus native Ollama. Docker is useful for isolation, but it can add friction when local model acceleration and host networking are involved.

When to use native macOS setup

You are using an M1, M2, M3, or M4 Mac and want local model inference through Ollama.
You want fewer Docker networking surprises while testing Odysseus for the first time.
You are comfortable running project scripts from a cloned GitHub repository.

Requirements

Current macOS with command line tools installed.
Git installed.
Ollama installed if you plan to use local models.
Enough unified memory for the model you plan to run.

Step-by-step

Clone the official repository, review the current README, and use the macOS launch script provided by the project. The script name used by the official setup is start-macos.sh.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
chmod +x start-macos.sh
./start-macos.sh

Connect Ollama

Before blaming Odysseus, confirm Ollama works directly on the Mac. Pull a small model first so the app can be tested without waiting for a huge download.

ollama pull qwen2.5:7b
ollama run qwen2.5:7b
ollama list

If Odysseus asks for an OpenAI-compatible endpoint, Ollama's default local API base is commonly exposed through port 11434. Check the current Odysseus model provider settings before saving.

Common mistakes

Running a model too large for your memory and assuming Odysseus is slow.
Starting Odysseus before confirming Ollama can run a model on its own.
Mixing Docker and native services without knowing which network namespace the app is using.
Closing the first-run terminal before saving the generated admin password.

Version note: Odysseus is moving quickly. If the official script changes, follow the script name and prerequisites from the current official README.