Configure your own AI with Caduceus

Caduceus does not ship a model. It routes / (chat) and /c (control this Mac) to whatever backend you pick in Settings → AI. Everything else — launcher, clipboard, dictation, web search — works with zero AI setup.

Started with the one-line app install? You can run the full stack installer later; it is idempotent and skips pieces you already have.

Path A — Hermes Agent (recommended for `/c`)

Hermes Agent is an open-source CLI from Nous Research. Caduceus talks to it locally; Hermes owns models, tools, memory, and computer_use screen control.

Install Hermes (Settings → AI → Open in Terminal, or run the install script yourself).
Run hermes setup --portal or point Hermes at Ollama with hermes model.
In Caduceus, set “/” and “/c” to Hermes Agent.

Docs: Hermes on GitHub.

Path B — OpenAI-compatible endpoint (your CLI or local server)

Use this if you already run Ollama, LM Studio, llama.cpp server, vLLM, or any HTTP API that speaks the OpenAI chat format. Caduceus calls it directly — Hermes is not required for /.

Start your server (example: ollama serve on port 11434).
In Caduceus: Settings → AI → Advanced: direct model endpoint → Add endpoint.
Set Base URL (e.g. http://localhost:11434/v1) and Model tag.
Add an API key only if your server requires one (stored in the macOS keychain).
Set Routing → “/” to that backend.

Base URL:  http://localhost:11434/v1
Model:     qwen3.5:4b

/c needs a backend with screen control. Today that means Hermes with computer_use enabled — a plain chat endpoint cannot drive the mouse.

Path C — Cloud APIs (OpenAI, OpenRouter, etc.)

Add an OpenAI-compatible backend with the provider’s base URL and model name. Put the API key in Settings (never stored in plain JSON — only the keychain). Costs depend on the provider; Caduceus itself is free.

Path D — Hybrid

Common setup: / → local Ollama (free, private), /c → Hermes with a vision model for screen tasks. You can add multiple backends and switch routing anytime.

Verify it works