Getting started

Pick the path that matches what you have. Each one stands on its own; they stack.

Path	You need	You get
A — Nemo	An Apple Silicon Mac and a CoeOS box or an OdyssAI-X engine to point it at	The desktop client: chat, cowork, code, with routing you can see
B — The CoeOS box	Any machine with Docker, and an OpenRouter key or a local engine	One address for every tool you own, each request routed to the best model per skill
C — The OdyssAI-X engine	One or more Apple Silicon Macs, Docker Desktop on the one that orchestrates	Frontier open-weight models served locally, OpenAI- and Anthropic-compatible

Most people start with B, then add A on their desk and C when they want the models at home.

---

Path A — Nemo

1. Download nemo-mac-arm64.dmg from the Releases page and drag Nemo to Applications. Signed and notarized: no Gatekeeper warning.
2. Open it. Allow Local Network access when macOS asks.
3. Settings → Providers: enter your CoeOS box’s URL (and its ck_… key if it requires one), press Test, save. Leave the URL empty and Nemo looks for a box or an engine on your network by itself.
4. Restart Nemo when the banner asks. Pick a model — or CoeOS, the router — and talk.

No box yet? Point Nemo straight at an OdyssAI-X engine (http://<engine>:8000) as an engine in the same tab. You get the engine’s models without routing. Full page: Nemo.

---

Path B — The CoeOS box

git clone https://github.com/Odyssai-eu/coeos-box.git && cd coeos-box
docker compose up -d --build
curl -s http://localhost:4600/health

Then, in the console at http://<host>:4600/dashboard:

1. Create your first user and key — with the admin flag, or you lock yourself out of the console:

   python -m coeos.accounts create-user you --admin
   python -m coeos.accounts issue-key you --name laptop      # prints ck_… once

2. Connect a provider — paste an OpenRouter key in the Providers tab, or give the built-in keyless odyssai provider the address of your engine (see Connect your models).
3. Say who serves what — the TMB Settings bind each competence axis to a model. The shipped settings are a starting point; change them as you like. Set a decider model if you want requests without an explicit axis header to be classified; until you do, they go to the default axis.

Every tool that speaks OpenAI or Anthropic now has one address:

export OPENAI_BASE_URL=http://<host>:4600/v1
export OPENAI_API_KEY=ck_…
curl "$OPENAI_BASE_URL/chat/completions" -H "authorization: Bearer $OPENAI_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"CoeOS","messages":[{"role":"user","content":"Write a Python script that…"}]}'

The response headers say who answered: x-coeos-axis, x-coeos-model, x-coeos-provider. Full page: CoeOS box.

---

Path C — The OdyssAI-X engine

One server (the orchestrator container; a Mac mini is enough) and one or more nodes (the Macs that hold the models; the server can be a node). The whole install is a terminal — or an AI agent following the repo’s AGENTS.md.

git clone https://github.com/Odyssai-eu/OdyssAI-X.git && cd OdyssAI-X
scripts/bootstrap-node.sh user@node.lan            # once per node, idempotent
scripts/wired-limit/install.sh user@node.lan 250880 # pin the GPU memory budget (needs the node's password)
mkdir -p ~/.odysseus && cp config/topology.example.yaml ~/.odysseus/topology.yaml
$EDITOR ~/.odysseus/topology.yaml                  # ssh targets, models_dir, backend
docker compose up -d
curl -s http://localhost:8000/health               # {"status":"idle","version":"…"}

Download a model from the dashboard (http://localhost:8000/, Models → Download), load it on a cluster, and chat on /v1/chat/completions. Single Mac? Use host.docker.internal as the SSH target; the example topology shows it. Full page: Install the engine.

---

Putting them together

Nemo  ──▶  the CoeOS box  ──▶  OdyssAI-X  (and / or cloud providers)

1. Give the box your engine’s address on its keyless odyssai provider.
2. In the TMB Settings, bind the axes you want served locally to the models your engine has loaded. A replica pool is the natural backend: one copy of the model per Mac, several conversations per Mac at once.
3. Point Nemo at the box. Its model picker shows CoeOS and every model the box publishes; each answer names the model that served it.

What next

• What CoeOS is — the idea behind the routing, and the paid suite for regulated professions.
• Guardian — detect confidential content before it leaves.
• OdyssAI-X overview — distributed, replica and VLM modes; the capability contract.
• TMB Scoreboard — where the routing table comes from.