Connecting Hermes Agent to the University OpenWebUI

Four steps, about 15 minutes. Afterwards an agent runs on the university server: your texts and files stay inside the university network. Set up once – the setting then applies to every session and every folder.

Hermes needs no file and no script for this: its settings live in one place for the whole machine anyway, and the desktop app has a test button that says immediately whether it worked.

At a glance

Step 1: Check reachability (1 minute)

Open https://openwebui.uni-freiburg.de in your browser.

The instance is reachable only from the university network. eduroam alone is not enough. VPN: download FortiClient from rz.uni-freiburg.de (Services → Netz & Telefon → VPN), create an SSL VPN connection with server fortivpn.uni-freiburg.de, username <Uni-Account>@uni-freiburg.de, password = your eduroam password.

Step 2: Get the key (2 minutes)

1. In OpenWebUI, click the profile icon at the bottom left.
2. Open Settings → Account (German: Einstellungen → Konto).
3. Scroll to the API keys section (German: API-Schlüssel) and click Show next to Secrets (German: Zugangsdaten → Anzeigen – the section is collapsed).
4. Click Create new secret key, then Copy API Key.

Exactly one key per account. A second click on Create new secret key invalidates the first – anything using it is rejected from that moment. The key can be displayed again at any time; it does not have to be renewed.

Step 3: Install Hermes (5 minutes)

Download the installer from hermes-agent.nousresearch.com and open it – use that source only; similarly named pages have nothing to do with the product.

• Windows: open the .appinstaller package, confirm with „Install".
• macOS: open the DMG, drag Hermes.app to „Applications" (Apple Silicon).

Then start Hermes from the Start menu or from „Applications".

Terminal only, without the desktop app – in PowerShell: iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Step 4: Connect (3 minutes)

1. Open Hermes, click the gear icon top right („Open settings").
2. On the left choose Providers → Custom Endpoints.
3. Under Add endpoint, fill in four fields:

Two fields stay empty: Provider ID (generated automatically) and Context (detected). Both are optional.

4. Click Test. Expected message: „The endpoint is reachable (Chat Completions route served). 43 models found."
5. Click Save. „Custom endpoint saved." appears.
6. Make sure the switch „Use for new chats" is on – then the university model applies to new sessions immediately, with no extra step.

The URL must end in /api/v1. …/api also works and is corrected by the test button; /v1 alone or the bare domain do not work.

Where this is stored: Hermes keeps everything in one configuration file for the whole machine (C:\Users\<YourName>\AppData\Local\hermes\config.yaml or ~/.hermes/config.yaml). There is no per-project setting – which is why after step 4 every folder and every session is covered automatically. You do not need to care about that file; it is only the reason nothing has to be copied here.

Step 5: Test (1 minute)

Start a new session and write: Say hello in one sentence and name your model.

If the model answers, you are done. If it describes itself instead of naming a model, that is not an error. If it does not answer, the cause is almost always in the table below.

Which model?

For agent work, the coding models. They are built for planning, tool calls and multi-step tasks – exactly what an agent needs when it reads files, runs commands and checks results.

The coding models are not only for programming: checking texts, searching folders and reshaping data also run more reliably with them, because they keep going across several steps. You can switch models at any time during a session.

Recommendation: set up in the desktop app, work in the terminal

Set Hermes up in the desktop app (steps 1–4). Four fields, one test button, and you see immediately whether it worked.

Then work in the terminal: start hermes --tui. That is where you see the agent reading files, running commands and changing code – in a window with chat bubbles it looks like a chatbot, in the terminal the difference is visible.

Both are the same installation: configuration, key and sessions are shared. You can switch at any time, in either direction.

If something does not work

Three things worth knowing

• One key, two tools. The same university key works in Hermes and in OpenCode. Anyone setting up both enters it twice but does not create a second key – a new key invalidates the old one in both tools.
• Two keys, two services. The OpenWebUI key works only for openwebui.uni-freiburg.de. The key for the internal service llmlb.ael.intra.uni-freiburg.de is a different key and not interchangeable – the wrong one gives 401. This guide needs only the OpenWebUI key.
• Thinking models. Nothing to do in Hermes: it separates reasoning and answer itself. Only your own scripts need a generous max_tokens (tested: about 900 is enough for an answer).

If you cannot use the desktop app

Setup also works without it. hermes model in the terminal walks through provider selection; that menu is long (more than 40 entries whose numbering shifts between versions), and the entry you want is called „Custom endpoint (enter URL manually)". Then start hermes --tui.

The result is the same: one config.yaml, the same providers, the same sessions.

The finished configuration