Install the stack

One app installs the whole fleet. Drag, click, build the topology, done.

This page installs the server side of OdyssAI: the OdyssAI-X orchestrator, the Companion chat client, and your engine nodes. It is the recommended, no-terminal path — a native macOS app called the OdyssAI Configurator clicks through a wizard and puts each component on the right machine.

Just one Mac and you only want to chat? You don’t need this page — see Telemak getting started (drag one .app).
Installing with an AI agent or a scripted setup? Jump to The CLI path.

What you are installing

Three components, each on its own machine. The orchestrator never runs inference itself — it routes requests to engine nodes or to a Telemak. That’s why a cheap Mac mini can drive expensive Mac Studios.

Component	What it is	Target machine
Serveur	OdyssAI-X orchestrator (`:8000`) + Companion chat client (`:3100`)	a Mac mini (Apple Silicon)
Engine	the MLX runner (`mlx` / `mlx-lm`)	each Mac Studio node
Telemak	single-Mac runtime (Solo mode)	any one Mac

Two deployment modes:

Cluster — Serveur + N Mac Studio nodes wired over Thunderbolt 5 (RDMA). For frontier models, 200 B–700 B.
Solo — Serveur + one Telemak Mac, driven over HTTP. No RDMA, no cluster.

A single Mac on its own is always Telemak, never OdyssAI-X — OdyssAI-X is the orchestrator-on-a-server. If that’s your case, stop here and go to Telemak.

What you need

Serveur → a Mac mini (Apple Silicon — the memory embedder needs it).
Engine → one or more Mac Studio (Apple Silicon, macOS 14+).
Network → for Cluster mode, one Thunderbolt 5 cable per node-to-node link, plus normal LAN. Remote Login (System Settings → General → Sharing) on every engine node, reachable by SSH key from the Serveur.
Disk → ~5 GB per node for the runtime, plus your models.

Step 0 — Get the Configurator

The Configurator is not signed with an Apple Developer ID (deliberate: distributed outside the App Store). So the first launch needs one unlock click.

Download OdyssAI-Configurator-<version>.dmg from the releases page, open it, and drag OdyssAI Configurator.app to Applications.
First launch is blocked by Gatekeeper. Unblock it without reinstalling:
- No terminal: open it once, dismiss the warning, then System Settings → Privacy & Security → Open Anyway.
- One line: xattr -dr com.apple.quarantine "/Applications/OdyssAI Configurator.app"

The wizard flow is always the same: Profile → Dependencies → Configuration → Installation → Topology → Validation.

Mode Cluster — Serveur + Mac Studios

1. Install the Serveur (on the Mac mini)

Launch the Configurator on the Mac mini, pick profile Serveur. The Dependencies step checks for Docker (and guides the install if missing); the Installation step brings up the Docker stack — OdyssAI-X, Companion, Postgres, and the memory embedder.

Result: OdyssAI-X on :8000, Companion on :3100. Verify:

curl -sf http://localhost:8000/health
# {"status":"idle","version":"…"}   ← idle, no model loaded yet

Open the dashboard at http://localhost:8000/.

2. Install the Engine on each Mac Studio

For every node, make sure the Serveur can SSH to it without a password (ssh-copy-id admin@<node-ip> once, if needed). Then in the Configurator pick profile Engine, enter the node’s SSH target and the shared models directory (the same path on every node). The wizard provisions the MLX runtime over SSH. It’s idempotent — safe to re-run after a reboot.

3. Build the topology

In the Topology step, enter each node as rank = ssh-target, choose backend jaccl, and click Build. The Configurator probes the Thunderbolt wiring, generates the RDMA matrix, validates mesh symmetry, and writes ~/.odysseus/topology.yaml (backing up the old one, preserving other clusters).

If a cable is unplugged it fails with a clear “X cannot reach Y” — fix the cabling and Build again. Confirm:

curl -s http://localhost:8000/admin/clusters    # your cluster name appears

Fresh node, RDMA won’t come up? A brand-new Mac’s Thunderbolt ports have no IPv6 link-local address, which JACCL needs. Provision the node once, at its console (never over SSH) via the Configurator’s node-setup → network step. Details in Cluster.

Mode Solo — Serveur + Telemak

Install the Serveur — same as Cluster step 1 (Mac mini, profile Serveur).
Install Telemak — on the single Mac that runs the model, pick profile Telemak; the Configurator drops Telemak.app in /Applications. Launch it and note its endpoint (e.g. http://<telemak-ip>:8003). See Telemak getting started for loading a model.
Wire it — in the Topology step choose backend http-proxy and set the upstream to Telemak’s URL. The Configurator writes the Solo cluster and validates it.

First model + smoke test

A model must exist under models_dir on every node before the orchestrator can load it. Download it (Hugging Face), then load + smoke:

# Load on the cluster (<cluster> = the topology key, e.g. "default")
curl -X POST http://<server-ip>:8000/admin/<cluster>/load \
  -H 'Content-Type: application/json' \
  -d '{"model":"mlx-community/Qwen3-7B-MLX-8bit"}'
# First load: 30 s – 5 min depending on disk + node count.

# Smoke a completion (/v1/* is always public)
curl -X POST http://<server-ip>:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"<cluster>","messages":[{"role":"user","content":"Say hello, sea."}]}'

A streaming response ending in data: [DONE] means the stack is installed. You can also download + load models from the dashboard (Sync matrix → Download from Hugging Face, then the cluster’s Load button).

Point Companion at the engine

Companion is already installed by the Serveur profile (:3100). Open it, create your admin account, then Settings → Infrastructure → Engine → http://<server-ip>:8000 → Test endpoint. Companion reads the capability contract and loads the catalog. See Companion getting started.

A few knobs

Cloud providers — Dashboard → Settings → Cloud providers → Add provider (OpenRouter / Anthropic / OpenAI), paste a key; aliases like or:claude-haiku appear in /v1/models immediately. (Do not install LiteLLM — it’s only a legacy fallback.)
Admin auth — /admin/* is open by default (trusted-LAN, single operator). Only set ODYSSAI_X_ADMIN_TOKEN if you expose the engine beyond your LAN. /v1/* stays public regardless.
Rebuild topology — moved a cable or added a node? Configurator → Topology → Rebuild re-probes, shows a before/after diff, re-validates, rewrites the file. No hand-editing.

The CLI path

The exact same install, driven by odyssai-configure — the idempotent CLI the GUI calls under the hood (JSON output, ships in the app bundle). This is the path for an AI agent or a scripted macOS setup:

odyssai-configure check-deps
odyssai-configure install orchestrator                 # OdyssAI-X (:8000)
odyssai-configure install server                       # Companion (:3100)
odyssai-configure install engine --node admin@<node-ip> -m <models-dir>
odyssai-configure topology build --cluster default --backend jaccl \
  --node 0=admin@<node-a> --node 1=admin@<node-b>

The full reference — every flag, the headless/Linux-orchestrator appendix, and the hard-won Thunderbolt onboarding gotchas — lives in the engine repo’s INSTALL-CLUSTER.md.

When it doesn’t work

Symptom	Fix
`docker compose` exits immediately	Bad `~/.odysseus/topology.yaml` or an unreachable SSH target — the boot log names the bad key.
Engine up, `/v1/models` empty	No model loaded — run the load step.
Topology Build “X cannot reach Y”	A Thunderbolt cable is unplugged or a node is off.
`errno 16 / 96 / 2` after a while	JACCL queue-pair degradation (known MLX bug) — reboot the nodes (dashboard has Reboot all).