Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / cli-sessions-and-platform-operations

CLI sessions and platform operations

Hermes provides one command-line product with several user-facing ways to start work, continue a conversation, connect messaging channels, and operate the local agent. The classic CLI, terminal UI (TUI), web dashboard, profiles, session store, gateway, and platform controls work together so a user can move between local and remote conversations without losing the session context. This page extends Command-line product with operational flows; see CLI setup and configuration and CLI installation, update, and recovery for adjacent lifecycle topics.

Interactive chat surfaces

The interactive surfaces turn a user prompt into a session-backed agent conversation. The classic CLI is the default terminal path, while the TUI adds a richer terminal view and the dashboard hosts that same TUI in a browser.

Classic CLI chat

The classic CLI is a prompt-driven chat surface for interactive work and one-shot requests. hermes and hermes chat can start a new conversation, resume an existing one, select a model or provider, preload skills, and run a non-interactive query. The session is saved so the user can continue it later with --continue or --resume.

The CLI also exposes slash commands for actions that do not need a new model turn. These commands let a user inspect the session, change its model or title, control work in progress, browse sessions, and move the conversation to a messaging platform. The same command registry supplies the commands shown on supported gateway platforms, so the command vocabulary stays aligned across surfaces.

TUI launch path

The TUI is selected by an explicit --tui flag, by the HERMES_TUI=1 setting, or by the configured interface when both standard streams are real terminals. --cli forces the classic interface. Non-interactive input stays on the classic path so pipes, cron jobs, and automation do not start a terminal-only UI.

The TUI keeps the composer, transcript, live work view, approvals, model picker, session picker, and slash commands in one interactive surface. It can keep more than one live session available, while switching to a cold session protects the current turn from an unsafe mid-stream change.

The launch choice and the shared session state follow this flow:

flowchart LR
    A[hermes or hermes chat] --> B{Interactive terminal?}
    B -- no --> C[Classic CLI or one-shot request]
    B -- yes --> D{Interface choice}
    D -- --cli --> C
    D -- --tui or configured TUI --> E[Terminal UI]
    C --> F[Session store and gateway-backed agent]
    E --> F
    F --> G[Transcript, tools, approvals, and resume state]

References: hermes_cli/main.py• L1725-1815 hermes_cli/main_tui_launch.py• L500-524 hermes_cli/commands.py• L44-77

Dashboard chat

The dashboard is a browser operations surface that also embeds the TUI. Its Chat page starts the real TUI in a terminal session and streams the terminal output to the browser, so chat behavior remains consistent with hermes --tui rather than becoming a separate chat product.

The dashboard can start a new chat in a selected workspace or resume a session from its session list. A profile switch changes the model, skills, memory, and session store used by the next chat. This makes the dashboard useful for remote access while keeping profile and session boundaries visible.

References: website/…/web-dashboard.md• L44-89 website/…/web-dashboard.md• L140-165 hermes_cli/…/dashboard.py• L76-101

Session and profile operations

Sessions preserve conversation identity across launches and platforms. Profiles preserve agent identity across sessions by giving each agent its own configuration, credentials, memory, skills, gateway state, and session store.

Session lifecycle

A session is the durable conversation unit. It records the source of the conversation, its title, model context, messages, usage data, timestamps, and links to related sessions created by compression or branching. CLI sessions normally use the local SQLite store, while gateway sessions use the same durable model with routing information for their originating chat.

Users manage sessions through both shell commands and slash commands:

NeedUser-facing surface
Start fresh/new or /reset
Resumehermes --continue, hermes --resume, /resume, or /sessions
Find historyhermes sessions list, the session picker, or dashboard search
Name or organize/title, hermes sessions rename, pin, archive
Preserve or share/save or hermes sessions export
Remove old datahermes sessions prune, archive, or delete
Reduce active context/compress

Resuming restores the conversation and normally returns the user to its recorded workspace. A user can override that workspace when needed. Compression reduces the active context but does not delete the stored transcript.

References: website/…/sessions.md• L9-28 website/…/sessions.md• L108-188 website/…/sessions.md• L315-392 hermes_cli/…/sessions.py• L15-130

Session switching and control

The TUI treats session switching as a live control problem. A new live session can run beside the current one, but resuming a cold session closes the current view and is guarded while a turn is active. This keeps streaming state and user input attached to the correct session.

During a turn, users can stop work, queue a follow-up, steer the next tool boundary, ask a side question, or run a background prompt in a separate session. The status bar and live work dock show enough state to distinguish the active turn from queued or background work.

References: ui-tui/…/session.ts• L191-217 ui-tui/…/session.ts• L84-123 ui-tui/…/core.ts• L687-739 ui-tui/…/useMainApp.ts• L612-691

Profile operations

A profile is an independent agent home. It lets one machine host separate assistants without mixing their settings, credentials, memories, skills, sessions, or gateway state. A profile can be selected with -p, made the sticky default with hermes profile use, or addressed through its generated command alias.

Profile commands cover the agent lifecycle:

  • profile create creates a blank profile or a controlled clone.
  • profile list and profile show describe identity and gateway state.
  • profile rename changes a named profile identity or sets the default profile display name.
  • profile export and profile import move a profile as a shareable archive.
  • profile delete removes a named profile after confirmation.
  • profile describe records the role that task routing can use to choose an agent.

Messaging channels are not copied by normal profile cloning. This prevents two profiles from claiming one bot credential. A user must opt in to channel copying and accept the ownership conflict risk.

References: website/…/profiles.md• L5-53 website/…/profiles.md• L176-226 website/…/profiles.md• L343-387 hermes_cli/…/profile.py• L8-164

Platform enrollment and messaging controls

The gateway connects Hermes to external messaging platforms and applies platform-specific identity, access, and delivery rules. Setup stores credentials and channel policy, while gateway commands control the running connection without requiring the user to edit files by hand.

Platform setup and enrollment

hermes setup gateway and the dashboard Channels page guide a user through platform credentials, allowlists, home channels, and enablement. A home channel is the destination used for notifications, scheduled results, and cross-platform handoff. Users can also set it from the destination chat with /sethome.

The platform catalog includes common channels such as Telegram, Discord, Slack, WhatsApp, Signal, Matrix, email, webhooks, and the API server. Plugin platforms extend the catalog without changing the core chat flow. Setup may use platform-specific onboarding, such as QR pairing for WhatsApp or bot creation for Telegram.

Self-hosted gateways that use the relay connector have a separate enrollment path. hermes gateway enroll exchanges a single-use enrollment token and the operator's identity token for gateway credentials, then stores the relay identity and delivery credentials. Managed installations do not self-enroll because the hosting system supplies those credentials.

References: hermes_cli/platforms.py• L7-67 hermes_cli/setup_platforms.py• L146-184 hermes_cli/main_platform_setup.py• L133-223 hermes_cli/gateway_enroll.py• L108-209

Messaging command controls

Messaging users can use the shared slash-command model for session and gateway actions. The command registry decides which commands are available on a gateway surface, and platform adapters publish commands in the syntax allowed by that platform.

The main user-facing controls are:

ControlPurpose
/help and /commandsDiscover available commands
/status and /profileInspect the current session and agent identity
/new, /resume, and /sessionsStart or select conversations
/stop, /pause, /approve, and /denyControl running work and approval requests
/sethome and /handoffConfigure delivery and move a session between surfaces
/send or platform delivery toolsSend a message to an external target
/platforms or dashboard ChannelsInspect channel availability and setup state

Access checks happen before command output is sent to an unauthorized user. Pairing gives an operator a way to approve users for a channel, while allowlists provide platform-specific access limits.

References: hermes_cli/commands.py• L83-184 hermes_cli/commands_platforms.py• L24-117 tests/…/test_platform_commands.py• L23-68 tests/…/test_platform_commands.py• L135-168

Platform actions

Plugins can request a small set of actions on live platform messages, such as adding a reaction or changing a thread title. These actions are not a general bypass around gateway access: the plugin needs the named capability, the active profile must resolve to the matching adapter, and the adapter must be connected.

Each action returns a success or error result and is logged. This gives user-facing plugins a stable way to report unavailable gateways, missing consent, invalid targets, and unsupported platform actions.

References: hermes_cli/platform_actions.py• L14-29 hermes_cli/platform_actions.py• L73-175 hermes_cli/platform_actions.py• L178-203

Dashboard operations

The web dashboard is a machine-level control surface for the local Hermes installation. It combines chat, session review, profile management, channel setup, gateway control, diagnostics, and usage views behind one browser endpoint.

Dashboard scope and access

A dashboard normally binds to localhost and needs no login. A non-loopback bind engages the authentication gate and refuses to start without a configured provider. This protects the dashboard because it can read and write secrets, configuration, session data, and operational state.

One dashboard can manage many profiles. The profile switcher selects the target for configuration, chat, skills, model, and MCP actions. Gateway processes and session databases remain per-profile even though the dashboard presents them from one machine-level view.

References: website/…/web-dashboard.md• L15-42 website/…/web-dashboard.md• L44-90 website/…/web-dashboard.md• L430-432 website/…/web-dashboard.md• L634-661

Dashboard management areas

The dashboard groups user-facing operations by the object they affect:

AreaMain purpose
StatusShow gateway health, active sessions, recent activity, and resource pressure
ChatStart or resume a profile-scoped TUI conversation in the browser
SessionsSearch, inspect, rename, export, archive, prune, or delete sessions
ProfilesCreate, select, describe, configure, rename, or delete agents
ChannelsConfigure, enable, test, and restart messaging platforms
PairingApprove or revoke messaging users
WebhooksCreate, enable, disable, and remove event routes
SystemRun diagnostics, backups, gateway controls, memory controls, and host checks

Changes made in the dashboard use the same underlying profile configuration and session state as the CLI. The dashboard is therefore an alternate control surface, not a second source of truth.

References: website/…/web-dashboard.md• L107-118 website/…/web-dashboard.md• L276-321 website/…/web-dashboard.md• L323-432

User-facing operational commands

Operational commands let a user inspect health, control long-running services, repair session state, and move data without entering an agent conversation. They are the shell-level companion to the dashboard's System, Sessions, Channels, and Profiles pages.

Gateway and channel operations

hermes gateway manages the long-running messaging process. Its lifecycle commands start, stop, restart, install, and report the gateway, while hermes setup gateway focuses on the credentials and channel policy that the gateway consumes. hermes pairing manages user enrollment, and hermes send targets an external channel from the command line.

The gateway can serve several profiles through one host process. Commands that act on a profile must therefore keep the profile scope explicit so a restart, credential change, or platform action cannot affect another agent.

References: hermes_cli/main.py• L1832-1838 hermes_cli/main.py• L3381-3407 hermes_cli/gateway_enroll.py• L201-243 hermes_cli/…/messaging.py• L173-205

Health and recovery operations

hermes status and hermes doctor help a user tell the difference between an unavailable service, a bad platform setup, and damaged local state. Session maintenance commands list, export, optimize, archive, prune, repair, and recover the session store. Destructive or offline operations use confirmation and refuse unsafe writes when another Hermes process owns the store.

The dashboard exposes many of the same actions as background jobs with live logs. This keeps long checks and backups out of the chat turn while still giving the operator a visible result.

References: hermes_cli/…/sessions.py• L130-220 hermes_cli/sessions_cmd.py• L100-195 hermes_cli/doctor_platform.py• L123-180 website/…/web-dashboard.md• L406-424

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the classic CLI and TUI launch precedence aligned with the non-interactive TTY guard.
  • Keep session picker, resume, dashboard Chat, and --resume behavior aligned for profile and workspace scope.
  • When adding a slash command, update the shared registry and confirm its gateway visibility and platform menu limits.
  • When adding a platform credential or setup path, keep CLI setup, dashboard Channels, enablement checks, and allowlist behavior aligned.
  • When changing profile ownership, check gateway routing, session stores, cloned channel credentials, and dashboard profile scope together.
  • When changing session-store writes, preserve the offline-operation guard used by CLI, dashboard, and gateway processes.

Important failure modes

TriggerConsequenceGuard
A TUI is selected for a piped or background requestThe terminal UI can exit without running the requested workThe launch path chooses the classic interface when stdin or stdout is not a TTY
A user resumes a cold session during an active turnStreaming state can attach to the wrong sessionTUI session switching blocks cold resume while busy; live-session creation remains separate
Two profiles claim the same messaging bot credentialOne adapter may be parked or two gateways may fight for one botNormal profile clones strip channel credentials and profile listing warns about shared credentials
A non-loopback dashboard has no auth providerThe dashboard must not expose secrets or control APIsThe server fails closed unless a password, Nous OAuth, OIDC, or another provider is configured
A platform user is not authorizedThe user receives pairing or access handling instead of agent command outputAuthorization runs before gateway command dispatch
Session maintenance runs while another Hermes process writes state.dbLive conversations can lose or reject state changesOptimize, prune, repair, and journal conversion require an idle store unless explicitly forced
Relay enrollment runs in a managed installLocal credentials would conflict with hosted provisioningManaged installs refuse self-enrollment and use orchestrator-provided credentials

Key files

FileWhy to read it
hermes_cli/main.pyMain chat dispatch and the connection between top-level commands and chat launch
hermes_cli/main_tui_launch.pyInterface selection rules and TUI process handoff
hermes_cli/commands.pyShared slash-command contract across CLI and gateway surfaces
ui-tui/…/useMainApp.tsTUI session, turn, transcript, and gateway event coordination
ui-tui/…/session.tsTUI session switching, background work, model, voice, and context controls
hermes_cli/…/sessions.pyShell session-management command surface
hermes_cli/sessions_cmd.pySession listing, export, cleanup, repair, and recovery behavior
hermes_cli/…/profile.pyProfile command vocabulary and profile lifecycle options
hermes_cli/profile_cmd.pyProfile status, selection, cloning, and identity operations
hermes_cli/setup_platforms.pyInteractive channel setup and home-channel enrollment flow
hermes_cli/gateway_enroll.pySelf-hosted relay enrollment and credential persistence
hermes_cli/commands_platforms.pyTranslation of shared commands into platform menus and limits
hermes_cli/platform_actions.pyCapability-gated plugin actions on live platform messages
hermes_cli/…/dashboard.pyDashboard and headless backend launch contract
hermes_cli/…/messaging.pyDashboard channel configuration, enablement, and connection status
hermes_cli/…/sessions.pyDashboard session listing, search, mutation, and safety guards
website/…/web-dashboard.mdProduct-level dashboard behavior and operator workflow
website/…/sessions.mdProduct-level session persistence, resume, search, and handoff behavior
website/…/profiles.mdProduct-level profile isolation, cloning, and gateway ownership