Configuration overview

Hermina keeps each agent's configuration and data in one persistent profile directory. Use the dashboard or task-specific CLI commands for normal changes; edit files directly only when you need an advanced Hermes option.

Configuration layers

There are three distinct layers:

Changing a client preference does not alter the agent. Changing an agent profile does not change other agents.

Agent profile files

The default installation stores agents under $HERMINA_HOME/agents/. With the standard installer, $HERMINA_HOME is /opt/hermina.

agents/<name>/
├── config.yaml          # Non-secret Hermes and Hermina settings
├── .env                 # Provider and channel secrets
├── SOUL.md              # Identity, behavior, and boundaries
├── type.txt             # container or angel
├── profile.json         # Display metadata
├── skills/              # Agent-specific skills
├── cron/                # Scheduled jobs and history
├── whatsapp/session/    # Linked-device credentials
├── queue.db             # Persistent task queue
└── sessions/            # Gateway conversation state

The profile is mounted into a container at /root/.hermes. The container filesystem can remain read-only while this profile stays writable and persistent.

Use the task-specific controls

Prefer these commands over manual YAML changes:

hermina model <agent>       # Provider, model, endpoint, reasoning, API key
hermina media <agent>       # Vision, transcription, and speech
hermina edit <agent>        # SOUL.md
hermina env <agent>         # .env secrets and compatibility values
hermina channel <agent>     # WhatsApp transport
hermina allowlist <agent>   # Allowed senders
hermina groups <agent>      # WhatsApp group policy
hermina commands <agent>    # Slash-command administrators and user commands
hermina matrix <agent>      # Matrix account and room policy

Without change flags, most configuration commands display the current value and usage examples.

Secrets versus normal settings

Store secrets only in .env or the management key file. Typical secrets include:

• LLM provider API keys.
• WhatsApp Cloud access tokens and app secrets.
• Telegram bot tokens.
• Matrix access tokens.
• Hermina API keys in api-keys.txt.

Normal settings belong in config.yaml: provider name, model, reasoning level, media choices, group policy, tool settings, and gateway behavior.

Never commit .env, api-keys.txt, WhatsApp session credentials, OAuth tokens, or database backups to Git.

When a restart is required

An active agent normally needs a restart after changing model, media, channel, permissions, or group policy. The corresponding CLI and API operations attempt to apply that restart automatically.

After a manual edit:

hermina restart <agent>
hermina logs <agent> --follow

Confirm three states independently:

1. The runtime is running.
2. The model responds in dashboard chat.
3. Each enabled channel is connected and accepts the intended senders.

Direct YAML editing

For an advanced Hermes feature that is not exposed in the dashboard, edit:

$HERMINA_HOME/agents/<name>/config.yaml

Before editing:

1. Back up the file.
2. Stop simultaneous dashboard or CLI configuration changes.
3. Keep indentation and YAML types intact.
4. Restart the agent.
5. Inspect logs immediately.

Hermes evolves independently, so confirm unfamiliar keys against the current Hermes configuration reference.

Backup and restore

For a complete operational backup, preserve:

• agents/
• profile/, groups/, workspace/, and settings/
• personas/custom/
• api-keys.txt in a separate secret store
• Custom Nginx, Caddy, firewall, and service configuration

Stop write-heavy workloads or use a filesystem/database-aware snapshot to avoid copying SQLite files mid-transaction.