Skip to content

Profiles & settings

Hermes supports multiple profiles (isolated agent homes — different models, memory, skills, workspaces) on one server. Profile selection is per-client, carried by a hermes_profile cookie, so two clients pointed at the same server can operate in different profiles simultaneously. Verified against api/routes.py, api/profiles.py.

Profiles

GET /api/profiles

Response 

{
  "profiles": [
    { "name": "default", "path": "<agent home>", "is_default": true,
      "is_active": true, "gateway_running": false,
      "model": "…", "provider": "…", "visible": true,
      "skill_count": 12, "enabled_skills": 12, "total_skills": 15 }
  ],
  "active": "default",
  "single_profile_mode": false
}

POST /api/profile/switch

Body { "name": "<profile>" }. Sets a Set-Cookie: hermes_profile=<name> and returns: 

{ "profiles": [ … ], "active": "work", "is_default": false,
  "default_model": "…", "default_model_provider": "…", "default_workspace": "<path>" }
This is a per-client switch (cookie + thread-local) — it does not mutate the server's process-global profile, so it's safe for concurrent clients. It invalidates the models cache and restarts the gateway watcher for that client.

  • 400 missing name · 404 invalid/unknown profile · 403 in isolated mode · 409 if an agent turn is running.

GET /api/profile/active

Response { "name", "path", "is_default", "default_workspace": "<path>|null" }. A lightweight "which profile am I in + where does it point" probe.

Settings

Instance-wide preferences (bot name, theme, update-check, sidebar visibility, token caps) plus the auth control surface.

GET /api/settings

Returns the full settings object (the password hash is stripped) with injected status fields: 

{
  "bot_name": "Hermes", "theme": "…", "check_for_updates": true,
  "show_cli_sessions": false,
  "max_tokens": null, "max_tokens_effective": null,
  "auth_enabled": false, "password_auth_enabled": false,
  "passkeys_enabled": false, "passwordless_enabled": false,
  "webui_version": "0.x.y", "agent_version": "0.x.y"
}
webui_version / agent_version are the running versions — useful for a client to display and for update checks.

POST /api/settings

Body — any settings keys to persist, plus special control keys that are acted on and not stored: _set_password, _current_password, _clear_password, _passwordless, _auth_disabled_acknowledged, max_tokens, bot_name.

Response — the saved settings (hash stripped) + max_tokens* status + auth_enabled / password_auth_enabled / logged_in. On a first-password bootstrap it may set the auth cookie.

  • 409 if the password is pinned by an environment variable while trying to change it, or when enabling passwordless without a passkey.
  • 403 on a remote first-password attempt without the local gate, or a wrong/missing current password.

Auth changes ripple to every client

Because auth is one shared secret per instance, changing the password or toggling auth here affects all clients. Handle the returned logged_in / auth_enabled flags and re-authenticate if needed. See Authentication.