light-heart-labs--ods
wehub-resource-sync
153 行
4.7 KiB
Markdown
153 行
4.7 KiB
Markdown
# ODS macOS Quickstart
|
|
|
|
> **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.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **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)
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
```bash
|
|
git clone https://github.com/Light-Heart-Labs/ODS.git
|
|
cd ODS/ods
|
|
./install.sh
|
|
```
|
|
|
|
The installer will:
|
|
|
|
1. **Detect your chip** — identifies Apple Silicon variant and unified memory
|
|
2. **Pick the right model** — selects optimal model size for your RAM
|
|
3. **Download llama-server** — native macOS arm64 binary with Metal support
|
|
4. **Download your model** — GGUF file sized for your hardware
|
|
5. **Start Docker services** — chat UI, search, workflows, voice, and more
|
|
6. **Install OpenCode** — browser-based AI coding IDE on port 3003
|
|
|
|
**Estimated time:** 5–15 minutes depending on download speed.
|
|
|
|
---
|
|
|
|
## Open the UI
|
|
|
|
- **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.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
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`.
|
|
|
|
---
|
|
|
|
## Managing Your Stack
|
|
|
|
```bash
|
|
./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 logs
|
|
```
|
|
|
|
---
|
|
|
|
## Hardware Tiers
|
|
|
|
The 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`
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Files & Locations
|
|
|
|
| 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` |
|
|
|
|
---
|
|
|
|
## Known Limitations
|
|
|
|
- **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
|
|
|
|
---
|
|
|
|
## Need Help?
|
|
|
|
- Support matrix: [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md)
|
|
- General FAQ: [../FAQ.md](../FAQ.md)
|
|
- General troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
|
|
---
|
|
|
|
*Last updated: 2026-03-05*
|