Using Hermes Agent with SoAI

Hermes Agent can use a SoAI model through a custom OpenAI-compatible Chat Completions provider and can load SoAI tools through its native remote-MCP client.

Prepare SoAI credentials

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown.
  2. For tools, open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a personal token also requires MCP usage (MCP_USE). Changing server mode or exposed tools also requires Configuration changes (CONFIG_PATCH).
  3. Open Models and copy the exact model ID. This requires Model read access (MODEL_READ). Choose a model whose capabilities include Chat Completions and tool calling when Hermes will use tools.

Configure model access

Add the following to ~/.hermes/config.yaml. Hermes reads the SoAI API key from the named environment variable. Set ssl_ca_cert to a CA bundle that contains the SoAI certificate authority. 

model:
  provider: custom:soai
  default: YOUR_MODEL_ID

providers:
  soai:
    base_url: https://SOAI_HOST:5090/v1
    key_env: SOAI_OPENAI_API_KEY
    transport: chat_completions
    default_model: YOUR_MODEL_ID
    models:
      - YOUR_MODEL_ID
    ssl_ca_cert: /path/to/soai-ca-bundle.pem
export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'
hermes -m YOUR_MODEL_ID -z 'Explain what this project does.'

Connect Hermes to SoAI in Hermes Dashboard

  1. Start hermes dashboard and open the local dashboard address it prints.
  2. Open Config, select the model section, and enter the same provider, default model, and SoAI base URL shown in the YAML above. Select Save.
  3. Open API Keys, store the SoAI key under the environment-variable name used by the provider, then start a new session. Existing sessions can use /reload to reload dashboard-managed keys.
  4. Open Models to select YOUR_MODEL_ID as the main model, then use Chat to send a verification prompt.

The dashboard edits the same profile-scoped configuration as the CLI. Check the profile switcher before saving when more than one Hermes profile exists.

Configure MCP access

Hermes expands ${VAR} references in remote-server headers at connection time, so the token does not need to be written into the YAML. Merge this entry into the same configuration: 

mcp_servers:
  soai:
    url: https://SOAI_HOST:5090/mcp
    headers:
      Authorization: "Bearer ${SOAI_MCP_TOKEN}"
    ssl_verify: /path/to/soai-ca-bundle.pem
    enabled: true
export SOAI_MCP_TOKEN='YOUR_MCP_TOKEN'
hermes mcp test soai

A successful test performs a live connection and lists exposed tools. The official Hermes documentation linked below covers filtering and timeout fields.

Connect Hermes to SoAI MCP in Hermes Dashboard

  1. Open MCP, select Add Server, and choose HTTP/SSE.
  2. Set the name to soai, the URL to https://SOAI_HOST:5090/mcp, and Authentication to Bearer token.
  3. Paste the personal SoAI MCP token and select Add. Hermes stores the secret in the selected profile's .env and keeps only an environment reference in config.yaml.
  4. Select Test for the server and confirm that Hermes lists the exposed SoAI tools.

Troubleshooting

A model failure is independent of an MCP failure. Check /v1/models, the custom provider name, model ID, and SoAI API key for inference. Check the /mcp URL, personal MCP token, server mode, and exposed-tool list for tools. Never set ssl_verify: false; supply the SoAI CA instead.

Related documentation