Odysseus AI
Back to setup

Odysseus AI macOS Setup

Last updated: June 6, 2026

On macOS, the main decision is simple: Docker is fine for the app, but native macOS is the practical route if you want Apple Silicon local model acceleration.

Quick answer

Use the native macOS script on an Apple Silicon Mac. It launches Odysseus at http://127.0.0.1:7860. Do not expect Docker on macOS to use the Metal GPU.

Copy command
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
./start-macos.sh

1. Requirements

  • - macOS on Apple Silicon or Intel, with Apple Silicon preferred for local models.
  • - Git installed locally.
  • - Python 3.10+ or the version required by the current official README.
  • - Homebrew is useful because the script may install or check native dependencies.
  • - Enough free disk space for model downloads if you use Cookbook or Ollama.

2. Run the Native macOS Script

Run the command from a normal terminal. Keep the terminal open while you confirm the first boot and generated admin password.

Copy command
git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
./start-macos.sh

Then open http://127.0.0.1:7860. If you try http://localhost:7000 after using this script, the browser may correctly fail because the native macOS script uses port 7860.

3. Docker on macOS: When It Still Makes Sense

Docker is still useful if your goal is to test the Odysseus app, use remote model providers, or connect to an Ollama server running on the host. The limit is GPU passthrough, not the web app itself.

Good fit for Docker

Testing the UI, bundled services, remote OpenAI-compatible providers, or Ollama running natively on the Mac.

Poor fit for Docker

Trying to make a Linux container use the Apple Silicon Metal GPU for local model serving.

4. Connect Ollama on macOS

Ollama is often the easiest local model backend on macOS. Pull a small model first and only move to larger models when memory is stable.

Copy command
ollama pull llama3.1:8b
OLLAMA_HOST=0.0.0.0:11434 ollama serve

If Odysseus runs natively on the same Mac, use http://localhost:11434/v1. If Odysseus runs in Docker while Ollama runs on the host Mac, use http://host.docker.internal:11434/v1.

5. Open Odysseus from Your Phone

Only do this on a trusted LAN or VPN. Keep authentication enabled before binding the app outside loopback.

Copy command
ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh
# Then open http://<your-mac-ip>:7860 from a trusted device

For public access, use a trusted reverse proxy or private access layer instead of exposing the raw app port.

6. Common macOS Problems

localhost:7000 does not open

For native macOS, open 127.0.0.1:7860. Port 7000 is the Docker and manual uvicorn default.

Models are slow

Start with a smaller quantized model. The app can run, but local serving still depends on memory and model size.

Docker cannot see Apple GPU

This is expected on macOS. Use native macOS plus Ollama or llama.cpp for Apple Silicon local acceleration.

Verify Against Official Docs

The native script and port defaults can change. Check the official GitHub repository before debugging stale commands.

FAQ

Can Docker on macOS use my Apple GPU for Odysseus AI?

No. The official README states that Docker on macOS cannot use the Metal GPU. Use the native macOS path for Apple Silicon local model acceleration.

What port does Odysseus use on macOS?

The native start-macos.sh path currently launches at http://127.0.0.1:7860, not localhost:7000.

Should I use Docker or native macOS?

Use Docker if you only want to test the app or connect a remote provider. Use native macOS if you want Apple Silicon local model serving through Ollama or llama.cpp.

Can I open Odysseus from my phone on macOS?

Yes on a trusted LAN or VPN if you bind to 0.0.0.0 and keep authentication enabled. Do not expose the raw app port directly to the public internet.

Does vLLM or SGLang work on macOS?

The official README says vLLM and SGLang are CUDA/ROCm-oriented and do not run on macOS for this setup. Use Ollama or llama.cpp for Apple Silicon local serving.

Installation support

Need hands-on installation support?

Setup Helper is the self-service planner. Installation Support is for users who want a human to review the route, diagnose logs, or get Odysseus running. We confirm scope and price before any payment.

Request Log Diagnosis

$49. Pay only after we confirm the scope.

Selected package

Best for

  • Docker, Ollama, port 7000, admin login, or GPU checks already failed.

You get

  • One focused log review
  • Likely root cause
  • Exact next checks
  • Credit toward Remote Install

Not included

  • Full remote install
  • Hardware driver surgery
  • Guaranteed large-model performance
Please do NOT send passwords or API keys.

Related Guides

Download Safely

Start from the official repository and avoid fake installers.

Setup Guide

Compare Docker, macOS, Windows, and Linux install routes.

Ollama Connection Error

Fix host endpoints, /v1 suffixes, and no-model states.

Fix localhost:7000

Understand why native macOS uses port 7860 instead of 7000.

Hardware Requirements

Choose a local model that fits your RAM and unified memory.

Security

Expose Odysseus safely only behind a trusted private access layer.