mlx-optiq
Integration · Hermes Agent

Hermes Agent

NousResearch's Hermes Agent is an open-source autonomous agent that connects to a model endpoint, executes tasks, and improves over time via memory and learned skills. It speaks the OpenAI Chat Completions API, which optiq serve exposes by default.

Quick start: optiq run

One command starts optiq serve for the model (or reuses one already running on the port), configures Hermes Agent for that session only, and launches it. When Hermes Agent exits, a server it started is stopped. Arguments after -- go to Hermes Agent.

terminalbash
# interactive
$ optiq run hermes -m mlx-community/Qwen3.5-9B-OptiQ-4bit

# one-shot, non-interactive
$ optiq run hermes -m mlx-community/Qwen3.5-9B-OptiQ-4bit -- chat -q "List the python files here." --yolo

A key saved by hermes setup in ~/.hermes/.env would otherwise override the local one (Hermes reloads that file over the environment). optiq run gives Hermes a session home that shares your memories, skills and sessions and carries the local key.

The steps below set up the same connection by hand, for when you run optiq serve yourself. See optiq run for every option.

1. Install Hermes Agent

terminalbash
# Official installer (macOS / Linux):
$ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
$ source ~/.zshrc   # or ~/.bashrc
$ hermes --version

Prefer not to curl | bash? Clone manually: git clone https://github.com/NousResearch/hermes-agent && cd hermes-agent && pip install -e .

2. Start optiq serve

terminalbash
$ optiq serve \
    --model mlx-community/Qwen3.5-9B-OptiQ-4bit \
    --mtp --mtp-depth 2 \
    --port 8080

3. Point Hermes at OptiQ

Easiest path is the interactive wizard, which writes ~/.hermes/cli-config.yaml for you:

terminalbash
$ hermes setup
# pick "custom" as provider, paste http://localhost:8080/v1 as base URL,
# paste your model id, and sk-optiq-local as API key.

$ hermes      # start interactive chat

Or declare optiq serve as a provider in ~/.hermes/config.yaml. Hermes 0.16 sends OPENAI_API_KEY only to openai.com, so a local endpoint's key comes from the variable its provider names:

~/.hermes/config.yamlyaml
providers:
  optiq:
    name: OptiQ
    base_url: http://localhost:8080/v1
    key_env: OPTIQ_API_KEY
    default_model: mlx-community/Qwen3.5-9B-OptiQ-4bit
terminalbash
export OPTIQ_API_KEY=sk-optiq-local

$ hermes chat -q "List the python files here." \
    -m mlx-community/Qwen3.5-9B-OptiQ-4bit --provider optiq --yolo

optiq run hermes does this for the session only, in a copy of your Hermes home, and leaves your own config.yaml alone.

On an OptiQ Cloud model

With an OptiQ Cloud login (optiq cloud login), Hermes Agent can run on one of OptiQ Cloud's models, billed per token from your balance. No local model is loaded.

terminalbash
$ optiq run hermes --cloud glm-5.3-flash
$ optiq run hermes --cloud deepseek-v4.1-flash

If you run optiq serve yourself, pick the model optiq-cloud/glm-5.3-flash or optiq-cloud/deepseek-v4.1-flash in the setup above; optiq serve --cloud-only serves only the cloud models. Only clients on the same Mac as optiq serve can use them. Prices and limits are on OptiQ Cloud.

Notes

  • Tool use is core to Hermes: the agent's learn-from-skills loop depends on function-calling. Use a model trained with tool calling (Qwen3.5-9B-OptiQ and up, Hermes-3-Llama variants).
  • Long-running sessions: Hermes accumulates memory in long context. Pair with --kv-config (see Serving) for decode speedup at 16k+.
  • Streaming: works.
  • --yolo: bypasses the per-tool approval prompt, required in non-interactive mode. Drop it for interactive sessions where you want to vet each tool call.
  • Verified: optiq run tested against Hermes Agent v0.16.0 (2026.6.5) on macOS (Apple Silicon), on a local model and on GLM 5.3 Flash and DeepSeek V4.1 Flash.