Configuration UI: No More YAML Editing

The Settings Panel

The Desktop app's Settings panel (accessible via the gear icon or keyboard shortcut) provides a GUI for the most commonly configured Hermes options. It does not expose every possible configuration setting -- complex nested YAML structures like custom fallback chains still require direct file editing -- but it covers the configuration workflow that matters most for day-to-day setup and maintenance.

The Settings panel is organized into sections: Providers, Models, Tools, MCP Servers, Gateway, and Sessions. This mirrors the logical structure of Hermes configuration, making it straightforward to find the setting you are looking for without knowing which YAML key it maps to.

Changes made in the Settings panel are written directly to the appropriate file: provider keys go to ~/.hermes/.env, preferences go to ~/.hermes/config.yaml. The panel is a safe editor for those files -- it validates input before writing, handles the correct format automatically, and prevents common mistakes like writing an API key to the wrong file.

The Providers Pane

The Providers pane is where you add, view, and manage API keys for all configured providers. Each supported provider appears in the list with its current authentication status -- authenticated (key present and valid), unauthenticated (no key configured), or pending OAuth (browser sign-in required).

To add a key for a provider, click on it in the list, paste your API key into the input field, and save. The key is written to ~/.hermes/.env and is immediately available for use. You do not need to restart the app or reload configuration.

The Providers pane also shows which models each provider makes available. Clicking on a provider expands its model catalog -- a searchable list of all models accessible through that provider, with basic metadata like context window size and capability flags. This is the same database the CLI uses for model selection, surfaced as a browsable UI.

Providers with OAuth authentication (xAI Grok OAuth, MiniMax OAuth, ChatGPT/Codex) have a browser sign-in button in their entry rather than an API key field. Clicking it opens your default browser to the provider's OAuth flow. After authorizing, the token is stored automatically and the provider shows as authenticated.

Tool Backend Installation

Hermes's tool backends -- the systems that power specific tool categories like code execution, web browsing, and file operations -- can be installed and managed from the Tools section of Settings. This is particularly useful for backends that require separate installation or configuration, like Docker-based sandboxes or specific browser automation frameworks.

The Tools pane shows each available backend with its current installation status and a one-click install or update button. For backends that require system-level dependencies (like Docker), the UI shows what is required and links to installation instructions rather than attempting to install the dependency itself.

This GUI installation flow is more reliable than manually following installation instructions, because it validates that dependencies are present before proceeding and provides clear error messages when something is missing. For new Hermes users, tool backend installation is often one of the most confusing parts of the setup process. The Desktop UI makes it substantially more approachable.

The Auxiliary-Model Warning

When you change your primary provider in the Settings panel, Hermes checks whether your current auxiliary model configuration is compatible with the new provider. If you have configured auxiliary tasks to route to a provider that requires different authentication than your new primary, the Settings panel shows a warning: Auxiliary model configuration may be affected.

This warning prevents a subtle misconfiguration: switching from OpenRouter to direct Anthropic while leaving auxiliary tasks pointing at an OpenRouter-specific model. Without the warning, the auxiliary tasks would silently fail when the agent next tries to use them. With the warning, you know to review your auxiliary configuration before proceeding.

When you see this warning, open the auxiliary model configuration (currently requiring direct YAML editing in config.yaml) and update the provider/model for each affected task. The Settings panel does not yet provide a full GUI for auxiliary configuration -- that is one of the areas that still requires YAML editing for now.

MCP Servers

The MCP Servers section of Settings lets you add, configure, and enable or disable MCP (Model Context Protocol) servers that extend Hermes with additional tools. Each MCP server exposes a set of tools that become available to the agent when the server is enabled.

Adding an MCP server requires a name, the server's command or URL, and any required environment variables. The Settings panel provides a form for each of these fields. Once configured, the server appears in the list and can be toggled on or off without removing the configuration.

For MCP servers that are already installed system-wide (via the Hermes Hub or the CLI), the Settings panel discovers them automatically and displays them in the list. You typically do not need to add these manually -- they appear in the UI as soon as they are installed.

What Still Requires YAML Editing

The Settings panel covers common configuration but not everything. Some options require direct editing of config.yaml:

• Auxiliary model routing (provider/model per task)
• Fallback provider chains
• Credential pool strategies
• Custom timeout values
• Environment variable substitution in config values
• Provider routing preferences for OpenRouter

For these settings, edit config.yaml directly using any text editor. The Desktop app reads the file on startup and picks up changes. You do not need to restart the app after editing config files -- a session refresh is typically sufficient to apply most changes.