Skip to content

MACOS-QUICKSTART.md

Latest commit

 

History

History
145 lines (105 loc) · 4.39 KB

MACOS-QUICKSTART.md

File metadata and controls

145 lines (105 loc) · 4.39 KB

Dream Server 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

git clone https://github.com/Light-Heart-Labs/DreamServer.git
cd DreamServer/dream-server
./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

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)
        ├── OpenClaw Agents (port 7860)
        ├── 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

./dream-macos.sh status          # Health checks for all services
./dream-macos.sh stop            # Stop everything
./dream-macos.sh start           # Start everything
./dream-macos.sh restart         # Restart everything
./dream-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

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 ~/dream-server/
Config ~/dream-server/.env
Models ~/dream-server/data/models/
llama-server binary ~/dream-server/llama-server/
OpenCode ~/.opencode/bin/opencode
OpenCode config ~/.config/opencode/opencode.json
LaunchAgent (OpenCode) ~/Library/LaunchAgents/com.dreamserver.opencode-web.plist
CLI tool ~/dream-server/dream-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?

Last updated: 2026-03-05