Status: Supported
The macOS installer runs end-to-end on Apple Silicon. One command gives you a full local AI stack with Metal-accelerated inference.
- Apple Silicon Mac (M1, M2, M3, M4 or later)
- Docker Desktop 4.20+ installed and running
- 16 GB+ unified memory recommended (8 GB minimum)
- 20 GB+ free disk space (model + Docker images)
git clone https://github.com/Light-Heart-Labs/ODS.git
cd ODS/ods
./install.shThe installer will:
- Detect your chip — identifies Apple Silicon variant and unified memory
- Pick the right model — selects optimal model size for your RAM
- Download llama-server — native macOS arm64 binary with Metal support
- Download your model — GGUF file sized for your hardware
- Start Docker services — chat UI, search, workflows, voice, and more
- Install OpenCode — browser-based AI coding IDE on port 3003
Estimated time: 5–15 minutes depending on download speed.
- Chat UI: http://localhost:3000
- Dashboard: http://localhost:3001
- OpenCode (IDE): http://localhost:3003
First user on the Chat UI becomes admin. Start chatting immediately.
macOS Host
├── llama-server (native, Metal GPU acceleration)
├── OpenCode web IDE (native, LaunchAgent)
└── Docker Desktop
├── Open WebUI (port 3000)
├── Dashboard (port 3001)
├── LiteLLM API Gateway (port 4000)
├── n8n Workflows (port 5678)
├── Qdrant Vector DB (port 6333)
├── SearXNG Search (port 8888)
├── Perplexica Deep Research (port 3004)
├── Hermes Agent + auth proxy (port 9120)
├── OpenClaw Agents (port 7860, deprecated optional)
├── TEI Embeddings (port 8090)
├── Whisper STT (port 9000)
├── Kokoro TTS (port 8880)
└── Privacy Shield (port 8085)
llama-server runs natively for full Metal GPU utilization. Docker containers reach it via host.docker.internal:8080.
./ods-macos.sh status # Health checks for all services
./ods-macos.sh stop # Stop everything
./ods-macos.sh start # Start everything
./ods-macos.sh restart # Restart everything
./ods-macos.sh logs llama-server # Tail llama-server logsThe installer auto-selects the best model for your unified memory:
| Unified RAM | Tier | Model | Context |
|---|---|---|---|
| 8–24 GB | 1 | Qwen3.5 4B (Q4_K_M) | 16384 |
| 32 GB | 2 | Qwen3.5 9B (Q4_K_M) | 32768 |
| 48 GB | 3 | Qwen3 30B-A3B (MoE, Q4_K_M) | 32768 |
| 64+ GB | 4 | Qwen3 30B-A3B (MoE, Q4_K_M) | 131072 |
When Hermes is enabled, the macOS installer enforces a 64K minimum for the active local context. If bootstrap mode is used, the first-run bootstrap model starts at 64K so the agent is usable while the full model downloads; after the swap, the full model keeps the model selector's chosen context, which may be 128K on larger tiers.
Override: ./install.sh --tier 3
| Issue | Fix |
|---|---|
| "Docker not running" | Start Docker Desktop, wait for whale icon in menu bar |
| "Not Apple Silicon" | Intel Macs are not supported — Apple Silicon (arm64) required |
| "Port in use" | Check for conflicting services: lsof -i :8080 |
| llama-server crashes | Check memory — your model may be too large for available RAM |
| Docker services slow to start | First launch pulls images (~10 GB); subsequent starts are fast |
| TEI embeddings container restarts | Normal on arm64 — runs via Rosetta 2 emulation, may need a minute |
| What | Where |
|---|---|
| Install directory | ~/ods/ |
| Config | ~/ods/.env |
| Models | ~/ods/data/models/ |
| llama-server binary | ~/ods/llama-server/ |
| OpenCode | ~/.opencode/bin/opencode |
| OpenCode config | ~/.config/opencode/opencode.json |
| LaunchAgent (OpenCode) | ~/Library/LaunchAgents/com.ods.opencode-web.plist |
| CLI tool | ~/ods/ods-macos.sh |
- ComfyUI (image generation) is not available on macOS — requires NVIDIA GPU backend
- Dashboard GPU info shows "Unknown" — macOS Metal is not detected by the Linux-based dashboard container
- TEI embeddings runs under Rosetta 2 emulation (linux/amd64) — functional but slower than native
- Support matrix: SUPPORT-MATRIX.md
- General FAQ: ../FAQ.md
- General troubleshooting: TROUBLESHOOTING.md
Last updated: 2026-03-05