Providers and models

Every agent needs a model provider. Provider choice affects quality, latency, cost, privacy, context length, tool calling, and which media features are available.

Recommended setup flow

View the current configuration:

hermina model <agent>

Set a hosted provider:

hermina model <agent> \
  --provider=openai \
  --model=gpt-4o-mini \
  --api-key=YOUR_API_KEY \
  --reasoning=medium

The provider key is written to .env. Model, endpoint, API mode, and reasoning settings are written to config.yaml.

Test a plain dashboard conversation immediately after changing providers. Add tools, channels, and schedules only after the base model works.

Built-in provider presets

Hermina currently includes presets for:

Provider catalogs change over time. A preset proves the expected protocol and default endpoint, not that every listed model is available on your account.

Reasoning level

Supported values are:

xhigh, high, medium, low, minimal, none

Higher reasoning can improve difficult multi-step work but usually costs more and responds more slowly. Use medium as a starting point, lower it for high-volume routine conversations, and raise it only for tasks that benefit from deeper planning.

hermina model <agent> --reasoning=low

Custom OpenAI-compatible endpoints

Override the base URL and API mode when using a self-hosted or compatible endpoint:

hermina model <agent> \
  --provider=openrouter \
  --model=my-org/my-model \
  --base-url=https://models.example.com/v1 \
  --api-mode=chat_completions \
  --api-key=YOUR_API_KEY

The provider ID still selects defaults and the environment variable used for the key. Verify the endpoint separately before debugging Hermina.

Local models

For Ollama:

hermina model <agent> \
  --provider=ollama \
  --model=qwen3:latest \
  --base-url=http://HOST_REACHABLE_FROM_AGENT:11434/v1

127.0.0.1 inside a Docker agent refers to that container, not the host. Use a host address reachable from the container network or run an appropriate network configuration.

Choose a model with a large enough context window and reliable tool calling. Hermes workflows can fail in subtle ways on small-context or weak tool-use models even when simple chat appears normal.

Media models

Model configuration and media configuration are separate:

hermina media <agent>

Example:

hermina media <agent> \
  --vision-provider=opencode-go \
  --vision-model=mimo-v2.5 \
  --stt-enabled=true \
  --stt-provider=local \
  --stt-model=base \
  --stt-language=en \
  --tts-provider=edge \
  --tts-voice=en-US-GuyNeural

Vision analyzes images, STT transcribes incoming audio, and TTS produces spoken replies. Each provider may require its own key in .env.

Common provider failures