---
name: operate-hermes-agent
description: Install, update, migrate to, configure, run, secure, and troubleshoot Hermes Agent across its CLI, TUI, desktop, dashboard, profiles, tools, skills, memory, models, goals, voice, sessions, worktrees, and terminal backends.
metadata:
  hermes:
    category: agent-portability
    tags: [hermes, cli, configuration, security, troubleshooting]
---

# Operate Hermes Agent

Start from the installed runtime and the active profile, then change only the state the user placed in scope.

## Establish the Active Runtime

1. Run `hermes --version`.
2. Identify the active profile and Hermes home before reading or changing configuration.
3. Use `hermes status` for a broad runtime check and the narrower status command for the affected subsystem.
4. Distinguish the installed launcher, the managed source checkout, profile state, and project-local context.
5. Refresh the matching official docs when command names, defaults, provider catalogs, or security behavior matter.
6. Use `hermes update --check` before proposing an update. Inspect dirty files,
   carried commits, divergence, and the install method before running the
   mutating updater.

## Choose the Operating Surface

- CLI conversation: `hermes` or `hermes chat`.
- Modern terminal UI: `hermes --tui`.
- Local management UI: `hermes dashboard`; do not expose it beyond localhost without an explicit authentication and network plan.
- Profile isolation: use Hermes profiles when config, credentials, memory, sessions, skills, or gateway state must be independent.
- Repository isolation: use Git worktrees for parallel or experimental coding sessions.
- Remote or isolated execution: choose the terminal backend deliberately; use containerized or managed backends for untrusted or unattended work.
- Editor integration: hand ACP registry, launch, handshake, and session work to
  `operate-acp-agent-integration`; use `hermes acp --check` as the local
  non-interactive preflight.

## Configure Through Owned Commands First

- Use `hermes setup` for first-run configuration.
- Use `hermes model` for provider authentication and model setup between sessions; use `/model` for switching among configured choices inside a session.
- Use `hermes tools` for toolset and per-tool backend selection.
- Use `hermes skills` for skill discovery, install, update, and tap management.
- Use `hermes portal info` only for Nous Portal and Tool Gateway routing state.
- Edit `config.yaml` or `.env` directly only when the CLI/dashboard cannot represent the needed setting or the task is explicitly config-file work.

## Import Existing Agent Configuration Safely

Use `hermes import-agent claude-code --dry-run` or
`hermes import-agent codex --dry-run` before migrating an existing setup. Review
the proposed instruction, permission, MCP, skill, and memory mappings item by
item. Hermes does not import API keys or credentials; configure providers
separately with `hermes setup` or `hermes model`.

The normal importer skips name conflicts. Use `--overwrite` only after reviewing
the destination state and preserving anything that must survive. Do not use
`--yes` together with `--overwrite` for an unreviewed home directory.

## Operate Persistent Goals And Voice

- Use `/goal draft <objective>` when completion criteria, evidence, scope, and
  stop conditions should be made explicit before autonomous continuation.
- Add quality gates with `/goal gate add <command>` only when the command is a
  deterministic, bounded proof. Use `/goal wait` for a real background process
  rather than consuming continuation turns by polling.
- Keep `/goal` single-session. Use Hermes Kanban for multiple independently
  scheduled workers; neither surface implicitly creates the other.
- Treat voice mode, wake-word listening, and desktop push-to-talk as separate
  microphone paths. Verify the selected input device and local-only exposure,
  and tune barge-in only from observed false triggers or missed speech.

## Protect Operator State

- Treat auth stores, `.env`, provider keys, messaging tokens, and managed-scope configuration as secrets.
- Prefer checkpoints and worktrees for risky repository changes; confirm checkpoint state before promising `/rollback` recovery.
- Keep command approval, user authorization, terminal isolation, tool allowlists, MCP filtering, and network exposure as separate controls.
- For unattended gateways, prefer Docker, Modal, or Daytona-style isolation over direct host execution when the workflow permits it.
- Do not run install, update, login, dashboard, gateway, or browser-opening commands when the user asked only for explanation or diagnosis.

## Diagnose by Layer

1. Launcher and version.
2. Active profile and config source.
3. Provider credentials and runtime resolution.
4. Model selection and API mode.
5. Toolset and backend selection.
6. Skill or plugin discovery.
7. Session, memory, or context-file state.
8. Terminal backend, permissions, and network reachability.
9. Gateway or hosted-service state, if involved.
10. Goal judge/gate or voice-device state, if involved.

Report the exact layer that failed and the next read-only check before proposing a mutation.

## Verification

Verify only the affected path. Examples:

- configuration: `hermes status` plus the subsystem status command;
- provider: provider/model status and one harmless prompt;
- skill: discovery plus explicit invocation;
- terminal backend: a harmless command in the selected backend;
- worktree: repository path and branch isolation;
- security: approval, authorization, or isolation state without performing a dangerous action.

Read [references/operator-surface-map.md](references/operator-surface-map.md) for state locations, commands, failure modes, and official sources.