A complete guide to installing Odysseus AI on Apple Silicon (M1/M2/M3/M4) and Intel Macs. Covers Homebrew prerequisites, the port 7860 AirPlay workaround, Metal GPU acceleration via Ollama, the MLX limitation, and includes an interactive model recommender that matches your exact Mac.
macOS is the friendliest platform for the Odysseus AI install — Homebrew handles almost everything. Three small prerequisites and you're done in 10 minutes.
Odysseus AI runs on macOS 13 and later, with macOS 14 Sonoma and 15 Sequoia being the explicitly tested versions. Older macOS releases miss the Python 3.11+ that Homebrew now ships, and the Metal acceleration in Ollama is significantly faster on macOS 14+. Check yours from the Apple menu → About This Mac.
The de facto package manager for macOS. If you don't already have it, install with the official one-liner:
After install, follow the post-install instruction Homebrew prints — it tells you to add /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel) to your shell PATH. Skip that and every subsequent brew command will fail.
Many of Odysseus AI's Python dependencies compile native code on first install. The Command Line Tools provide the compilers. Trigger the install with:
If you already have it, the command returns "command line tools are already installed" — that's fine, move on. The full Xcode app is not required.
Open Terminal (or iTerm2 if you prefer) and run these in any folder where you want the project to live. ~/Code or ~/Documents are common picks.
One command installs both. Homebrew detects Apple Silicon vs Intel automatically and pulls the right binaries.
The official Odysseus AI repo lives at pewdiepie-archdaemon/odysseus. Always clone from this exact path to avoid impostor and mirror repositories.
The included shell script creates a Python virtual environment, installs dependencies via pip, then starts the Odysseus AI server on port 7860.
First run takes 2–5 minutes to download dependencies. The admin password is printed once — copy it before scrolling.
Once you see "Uvicorn running on http://0.0.0.0:7860", switch to Safari, Chrome, or your browser of choice:
Log in with admin and the password from your terminal. You're in. The next sections cover wiring up Ollama and choosing the right model for your Mac.
If you saw the homepage docs saying Odysseus AI runs on port 7000, you're not wrong — that's the default everywhere except macOS. Apple uses port 7000 for AirPlay Receiver, so the macOS launcher uses 7860 instead.
The macOS launcher already defaults to 7860. Just remember to use http://localhost:7860 instead of localhost:7000 in every bookmark, documentation snippet, and tutorial you read.
If you don't use AirPlay to stream to your Mac from another device, turn the receiver off and reclaim port 7000.
PORT=7000 ./start-macos.shIf a previous Odysseus AI run didn't exit cleanly, port 7860 might still be held. Find and kill the holder:
Ollama on macOS is exceptional — full Metal GPU acceleration on Apple Silicon with zero configuration. This is the fastest way to run local models inside Odysseus AI.
Two options. The official native app is friendlier; Homebrew is more script-friendly.
Both options register Ollama as a background service. After install, you'll see the Ollama icon in your menu bar.
The general rule for Apple Silicon: pick a model where the quantized size is ~60% of your unified memory. The model recommender below picks the optimal one for your exact configuration.
In Odysseus AI, click the settings gear → Providers → Add Provider → OpenAI-compatible:
Save, refresh, and your pulled model appears in the chat dropdown. Send a test message — on Apple Silicon you should see 20–40 tokens per second on a 7B model.
Pick your Mac model and RAM. The tool ranks four model sizes against your unified memory, predicts inference speed, and gives you the exact ollama pull command for the top match.
Honest predictions based on real Apple Silicon benchmarks — not vendor marketing.
Both platforms work, but the performance gap is enormous. If you're choosing a Mac for the Odysseus AI install, Apple Silicon isn't a "nice to have" — it's the difference between fluid AI workflows and a frustrating slideshow.
Apple Silicon's unified memory architecture lets the GPU and CPU share the same RAM at the same speed. On an Intel Mac, model weights have to be copied between system RAM and GPU VRAM — a process that's often slower than just running everything on CPU. The Metal Performance Shaders framework also got serious LLM optimization in 2024 and 2025, adding another 2–3x speedup that Intel Macs can't access.
If you're on an Intel Mac and want to run Odysseus AI seriously, the pragmatic answer is: use it with API providers (OpenAI, Anthropic, OpenRouter) and skip local models entirely. The workspace experience is identical; you just trade local privacy for cloud inference speed.
Apple's MLX framework is genuinely exciting — purpose-built for Apple Silicon, often faster than llama.cpp on the same hardware. But there's a practical mismatch with how Odysseus AI talks to models, and it's worth understanding.
Odysseus AI connects to model backends through the OpenAI-compatible REST API. Ollama, llama.cpp server, vLLM, and LM Studio all expose this interface. MLX itself doesn't ship a server with this interface — it's a Python framework for direct model loading and inference, not a service.
Virtually every model that has an MLX version also has a GGUF version. GGUF models run through Ollama or llama.cpp with full Metal acceleration on Apple Silicon — speed difference vs MLX is usually under 20%. For now, that's the right path inside Odysseus AI.
A community project called mlx-omni-server wraps MLX models in an OpenAI-compatible HTTP server. It's not officially supported by Odysseus AI but works in practice. Configure it as a custom OpenAI provider with base URL http://localhost:10240/v1. Expect rougher edges than the Ollama path.
// landfall checklist
http://localhost:7860 opens the Odysseus AI login pageThese cover the failures unique to the macOS Odysseus AI install. Most are Homebrew, permission, or Python path issues.
AirPlay Receiver holds port 7000 by default on macOS. The launcher uses 7860 to avoid this, but if you explicitly set PORT=7000 you'll hit the conflict.
Homebrew was installed but the install script's PATH instruction was missed. Different paths for Apple Silicon vs Intel.
Xcode Command Line Tools are missing. Some Python dependencies need a C compiler at install time.
The script doesn't have execute permission. Common after cloning over certain mount points.
Rare but happens after macOS updates. Restart Ollama; if that doesn't fix it, reinstall.
Python's certifi bundle is out of sync — common after a fresh Python from Homebrew on a Mac without the Apple cert chain.
PORT=7000 ./start-macos.sh.git pull to fetch new code, then re-run ./start-macos.sh — the script detects changes to requirements.txt and installs new dependencies. Your chat history, settings, and downloaded models are preserved.http://<your-mac-ip>:7860 from Safari on iPhone/iPad. Your Mac must stay awake — disable sleep in Energy Saver, or use caffeinate in Terminal. Don't expose port 7860 to the public internet without HTTPS and authentication in front.