Manage agents

An agent is an independent Hermes profile with its own identity, provider, tools, data, channels, and runtime. Most daily operations are available from the Agents workspace and the CLI.

Agent lifecycle

The normal lifecycle is:

1. Create the profile and runtime definition.
2. Configure model, persona, channels, and permissions.
3. Start the container or service.
4. Pair channels that require interactive authentication.
5. Operate through chat, schedules, queues, and tools.
6. Stop, restart, or remove the runtime when needed.

The default runtime is a Docker container. Advanced angel agents run as systemd services on the host and should be treated as higher-trust workloads.

Create an agent

From the dashboard, open Agents, choose New agent, and work through the identity, model, persona, and channel steps.

From the CLI:

hermina add analyst 5511999999999 \
  --display-name="Research Analyst" \
  --lang=en \
  --start=true

Then set the provider separately:

hermina model analyst \
  --provider=openrouter \
  --model=openai/gpt-4o-mini \
  --api-key=YOUR_API_KEY

Agent names should be lowercase and stable. The name becomes part of the profile directory, container name, service name, API routes, and saved references.

Start, stop, and restart

hermina start analyst
hermina stop analyst
hermina restart analyst

Use restart after manual file edits. Task-specific commands such as hermina model, hermina media, and hermina commands normally restart an active runtime when required.

Inspect all agents:

hermina list
hermina status

The list distinguishes runtime state from channel state. A running container can still have a disconnected WhatsApp bridge or invalid model credentials.

Chat and sessions

Dashboard chat calls the Hermina control plane, which starts Hermes in the selected agent profile and streams events back as newline-delimited JSON. The UI displays tool steps and response text as they arrive.

Sessions are persistent. Use the session sidebar to resume earlier work, create a clean session, or pin and save important messages.

From the CLI, inspect or clear channel sessions:

hermina sessions analyst
hermina sessions analyst --json-output=true
hermina sessions analyst --clear=true

Clearing sessions can remove channel state or conversation continuity. Review the displayed session list before destructive actions.

Logs and health

hermina logs analyst
hermina logs analyst --follow
hermina bridge analyst

Use logs to separate these failure classes:

• Container or service failed to start.
• Hermes configuration could not load.
• Provider authentication or model request failed.
• Channel adapter started but is not connected.
• A tool or scheduled task failed after the agent was otherwise healthy.

Shell access

The dashboard shell and hermina shell are administrative capabilities:

hermina shell analyst "pwd && ls -la"

For container agents, commands execute inside the agent runtime. For angel or root profiles, the effective access can reach the host. Do not grant shell access to untrusted operators or clients.

Remove an agent

hermina remove analyst

To remove the runtime while preserving its profile data:

hermina remove analyst --keep-data=true

Back up the agent directory before permanent deletion. It contains identity, model settings, secrets, channel credentials, history, queue data, cron jobs, and skills.

Data owned by an agent

The important profile files are:

See Configuration overview before editing these files directly.