Hermes Agent with mittwald AI Hosting

‍

Compatibility notice

This documentation requires the following mStudio features which might not be available in all hosting plans: AI/LLM hosting‍.

Hermes Agent‍ is a command-line agent with file, shell and web tools, a built-in skill library, and MCP support. It reaches mittwald AI Hosting through a custom provider entry.

Installation

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Check the install:

hermes --version

Pointing Hermes at mittwald AI Hosting

Hermes reads ~/.hermes/config.yaml. Add an entry under providers: and make it the default:

model:
  default: Qwen3.8-27B-NVFP4
  provider: mittwald
providers:
  mittwald:
    api: https://llm.aihosting.mittwald.de/v1
    api_key: sk-...
    models:
      Qwen3.8-27B-NVFP4:
        context_length: 256000
      Qwen3.6-35B-A3B-FP8:
        context_length: 256000

Replace sk-... with your AI Hosting API key. You create it in the AI-Hosting section of your mStudio project — see Gaining access‍. An mStudio API token from your profile settings is a different credential and will not work here.

An entry under providers: accepts these keys: api (also spelled base_url or url), name, api_key, key_env, key_cmd, transport (or api_mode), default_model (or model), models, context_length, rate_limit_delay, request_timeout_seconds, stale_timeout_seconds, discover_models, extra_body, extra_headers, capabilities, ssl_ca_cert, ssl_verify, catalog_provider and session_affinity_header. Hermes ignores any other key and only records it in ~/.hermes/logs/errors.log — see Checking the config and the endpoint separately‍ — so check spelling against this list if the provider misbehaves.

Instead of pasting the key into config.yaml as api_key, you can keep it out of the file entirely with key_env and read it from an environment variable, set in your shell or in ~/.hermes/.env:

key_env: MITTWALD_LLM_API_KEY

Note

context_length is set per model under models. Both models above accept 256,000 tokens. A context_length directly on the entry would apply to every model in it.

Verifying the connection

Run hermes doctor as a first check:

hermes doctor

doctor surfaces common environment and setup problems, but its output varies by installation, and it doesn't report misspelled keys inside a providers: entry — Hermes ignores them without a warning on the terminal. If the provider doesn't behave as expected, check spelling against the key list in Pointing Hermes at mittwald AI Hosting‍ rather than trusting doctor to catch it.

Then run one turn that forces a tool call, because a plain chat reply would succeed even if tool calling were broken:

hermes chat --oneshot --model Qwen3.8-27B-NVFP4 \
  -q "Create a file called hello.txt containing the word hello, then read it back."

Two things about this command differ from what you might expect:

• There is no -p flag. The query flag is -q/--query. In an interactive terminal, -q only starts a chat session with that first message; --oneshot makes Hermes answer and exit.
• You don't need --provider. Hermes picks up mittwald from model.provider in config.yaml, so -m/--model is all you need to add. --provider mittwald works too, because the flag accepts the keys under providers: as well as Hermes' built-in provider names.

A successful run shows the agent preparing a write_file call, printing a diff of what it's about to write, then preparing a read_file call, then a final message confirming the round trip:

  ┊ ✍️ preparing write_file…
  ┊ review diff
a/hello.txt → b/hello.txt
@@ -0,0 +1 @@
+hello
  ┊ 📖 preparing read_file…

╭─ ⚕ Hermes ──────────────────────────────────────────────────╮
Done! Created `hello.txt` with the word "hello" and read it back:

```
hello
```
╰─────────────────────────────────────────────────────────────╯

Two separate tool calls, write_file then read_file, both against the mittwald endpoint — that is tool calling working end to end.

Recommended skills, plugins and MCP servers

Skills

Hermes ships a skill library — nothing to install. List what is available:

hermes skills list

Useful for development work:

• codebase-inspection — lines of code, languages and code-to-comment ratios of a repository
• github — pull requests, issues, code review and repositories through the gh CLI

MCP servers need no skill: Hermes connects to them itself, see MCP servers‍. The optional mcporter skill lists, authenticates and calls MCP servers from the terminal; install it with hermes skills install official/mcp/mcporter.

More skills come from registries:

hermes skills search <term>
hermes skills inspect <name>    # preview before installing
hermes skills install <name>
hermes skills audit             # re-scan installed skills

Review third-party skills before installing them

A skill is a set of instructions the agent will follow. Installing one from a registry means running someone else's instructions against your code. Use hermes skills inspect to read a skill first, and hermes skills audit to re-check what is already installed.

Plugins

Plugins install from Git repositories:

hermes plugins install owner/repo
hermes plugins list

Nothing is required for mittwald AI Hosting to work — the provider config above is sufficient.

MCP servers

MCP servers give the agent tools beyond files and shell. Add one, then test it:

hermes mcp add context7 --command npx --args -y @upstash/context7-mcp
hermes mcp test context7
hermes mcp list

A useful starting set:

Server	Command
Library documentation	npx -y @upstash/context7-mcp
URL fetching	uvx mcp-server-fetch
Browser automation	npx -y @playwright/mcp
Filesystem access	npx -y @modelcontextprotocol/server-filesystem <path>

mittwald's own MCP server exposes your infrastructure to the agent:

hermes mcp add mittwald --url https://mcp.mittwald.de/mcp --auth oauth
hermes mcp test mittwald

For the API-token alternative and troubleshooting, see Getting Connected with Hermes Agent‍.

Troubleshooting

Unknown provider 'mittwald'

Hermes didn't find a provider with that name. --provider and model.provider accept Hermes' built-in provider names and the keys under providers: in config.yaml. Check that the key under providers: is spelled exactly like the name you pass, and that the entry has a valid api URL — Hermes drops an entry without one.

Legacy custom_providers entry 'mittwald' has no providers: twin

hermes doctor shows this warning if your config still defines the provider in a top-level custom_providers: list, the format older Hermes versions and earlier versions of this guide used. Hermes still reads the list, but everything else in Hermes edits providers: only. Move the entry under providers: as shown in Pointing Hermes at mittwald AI Hosting‍ and delete the list. The old key names still work there, but the current names are api instead of base_url, default_model instead of model, and transport instead of api_mode. To set context_length per model, turn the models list into a mapping.

Checking the config and the endpoint separately

hermes doctor and a forced tool call cover two different failure modes, and it's worth knowing which one you're diagnosing:

• hermes doctor checks the structure of config.yaml, but it doesn't report a misspelled or unsupported key inside a providers: entry. Hermes ignores such a key and only records it in ~/.hermes/logs/errors.log, as providers.mittwald: unknown config keys ignored: …. Check spelling against the key list in Pointing Hermes at mittwald AI Hosting‍, or search the log for that message.
• If the config parses but the endpoint, key or model is wrong, doctor won't catch it either, because it doesn't call the endpoint. A forced tool call (as in Verifying the connection‍) is what confirms the mittwald endpoint is actually reachable and returning tool calls.

The agent keeps repeating the same tool call

The agent reads the same file again and again and never gets to an edit. Hermes notices such a loop and appends a warning to the tool result, but in an interactive session it doesn't stop the loop by default, and every iteration counts against your token quota. Turn on the hard stop and cap the iterations per turn in ~/.hermes/config.yaml:

tool_loop_guardrails:
  hard_stop_enabled: true
agent:
  max_turns: 30

With hard_stop_enabled, Hermes ends the turn once the same call has returned the same result five times in a row (hard_stop_after.idempotent_no_progress) and tells you which guardrail fired; reply continue to resume. max_turns is the maximum number of tool-calling iterations per turn and is unlimited by default. When the agent reaches it, Hermes asks the model to wrap up and allows one more call for a final answer. For a single run, pass --max-turns 30 to hermes chat instead.

The limits end a loop but don't prevent it. Loops happen mostly with thinking off. With Qwen3.8-27B-NVFP4, keep thinking on for planning and tool work, see Agent loops in non-thinking mode‍. The model thinks by default, so check that you haven't switched thinking off in the provider entry, for example with enable_thinking: false under extra_body.

Next steps

• Pi‍ — a second CLI agent
• opencode‍ — a third
• Getting Connected with Hermes Agent‍ — manage mittwald infrastructure from the agent
• AI models‍ — the full model list

Disclaimer

Third-party tools, MCP servers and external links are provided for convenience without endorsement or warranty. Use them at your own risk, review licenses and privacy policies, and scope access conservatively (least privilege). Avoid sending sensitive data to external services unless required and permitted.