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-setup-and-configuration

CLI setup and configuration

CLI setup turns a new or existing Hermes profile into a usable agent. It gathers model access, terminal execution, tools, messaging, and agent choices, then stores the result so the CLI, gateway, and other product surfaces use the same profile state. The command-line product owns the wider CLI experience; this page explains how that experience becomes ready to run.

Bootstrap and setup flows

First-run bootstrap

The first-run path checks whether the active profile has a usable provider, model choice, or saved authentication state. If it finds none, an interactive terminal can start hermes setup; a headless process stops with instructions instead of opening prompts that cannot be answered. This keeps an unconfigured profile from making an unintended provider choice.

The profile is selected before setup reads its files. A -p profile flag or the active profile choice changes the profile home for the whole command, so setup changes stay within that profile. Profiles are separate configuration islands rather than layers over the default profile.

The bootstrap relationship is:

flowchart TD
    A[Start CLI in active profile] --> B[Check provider and model readiness]
    B -->|Ready| C[Load configuration and run command]
    B -->|Not ready, interactive| D[Offer hermes setup]
    B -->|Not ready, headless| E[Show setup guidance and stop]
    D --> F[Save profile configuration]
    F --> C

References: hermes_cli/main.py• L593-665 hermes_cli/main.py• L1092-1186 hermes_cli/main.py• L1662-1692

Setup wizard modes

The setup wizard in hermes_cli/setup.py provides a full path and smaller paths for different starting states. A first install can use Nous Portal OAuth, configure every choice, or start with a blank slate. An existing install normally opens a reconfigure flow that keeps current values as defaults; --quick only fills missing items. A portal run is a one-shot path that selects a Nous model and can enable the Tool Gateway without running the rest of the wizard.

The full wizard moves through the product capabilities in a stable order:

AreaProduct purpose
Model and providerChoose the service and model that answer agent requests
Terminal backendChoose where commands and code run
Messaging gatewayConnect chat platforms and make the gateway active
ToolsEnable tool groups and their credentials
Shared metricsDecide whether bounded usage data stays local or is sent
Agent settingsSet turn limits, progress display, and context compression

The wizard can run one area alone, so an operator can change a provider or execution backend without repeating unrelated choices. Setup backs up the current configuration before reset or reconfiguration and re-reads configuration after provider flows save their own state.

References: hermes_cli/…/setup.py• L8-38 hermes_cli/setup.py• L592-623 hermes_cli/setup.py• L628-755 hermes_cli/setup_quick.py• L57-139 hermes_cli/setup_quick.py• L222-333

Imported setup state

On a first run, setup can detect an OpenClaw installation and show a dry-run import preview before it changes the Hermes profile. The user must confirm the import, and existing Hermes values take priority during the normal migration path. Imported messaging and instruction data can have different meaning, so setup calls out those high-impact areas before they become active.

After an import, setup can skip sections that already have meaningful state while still ensuring the gateway service exists when imported platforms or scheduled work need it. The result is a guided continuation rather than a silent overwrite of imported choices.

References: hermes_cli/setup_migration.py• L123-131 hermes_cli/setup_migration.py• L254-326 hermes_cli/setup.py• L628-662

Configuration loading and persistence

Configuration sources

Hermes uses the active profile home as the boundary for configuration. The main user file is config.yaml; .env holds secrets and environment-backed settings; managed installations can add an administrator-controlled overlay. The loader expands ${VAR} references and combines these sources before consumers use the result.

There are three useful views of configuration:

ViewPurpose
CLI configurationMerges CLI defaults with the user file and mirrors values needed by CLI tools
General configurationMerges DEFAULT_CONFIG with the user file, environment references, and managed values
Effective user configurationPreserves whether a key is truly absent, then expands and overlays it without adding defaults

The last view matters for presence-sensitive systems. For example, a missing setting can mean “use the platform default,” while a default-filled view would look like an explicit user choice. Gateway and other runtime readers use the effective view when that distinction affects behavior.

References: hermes_cli/cli_config_load.py• L258-297 hermes_cli/config.py• L2072-2083 hermes_cli/config_effective.py• L1-12 hermes_cli/config_effective.py• L52-62

Configuration writes

Configuration writes preserve the user file as a document rather than treating it as a disposable data dump. Normal writes change named values without deleting unrelated settings; full replacement is reserved for deliberate removal or reset. The write path is atomic and keeps comments and layout where possible, which lets setup and hermes config share one safe persistence contract.

New default keys normally become available through the merged view without being written into every user's file. This keeps future default changes visible and leaves the file focused on user choices. Managed values are not written back by local setup, because the administrator remains the owner of those settings.

References: hermes_cli/config.py• L2051-2070 hermes_cli/config.py• L2430-2500

Configuration migrations

The configuration version marks the schema understood by the current release. Migration validates the YAML before changing related files, applies registered steps in order, records the latest version, and preserves explicit user choices when a change only updates an old default. A file without a version is treated as current-schema content with only legacy-key migrations applied.

Very old stamped files below the support floor are not rewritten automatically. Hermes leaves them intact and asks the operator to back up the file and run setup or review the required version change. A migration step that fails is reported and does not silently pretend that its transformation succeeded.

References: hermes_cli/config.py• L1263-1368 hermes_cli/config_version_stamp.py• L26-74 hermes_cli/config_migrations.py• L19-35 hermes_cli/config_migrations.py• L852-874

Environment routing

Environment routing keeps secrets out of config.yaml and keeps environment-first readers aligned with setup. Provider keys, tokens, passwords, and platform values are saved in the profile .env; nested settings and non-secret product choices belong in config.yaml. A bare uppercase environment-shaped name passed to hermes config set is routed to .env, while a dotted name is routed to YAML.

Some YAML settings have a deliberate runtime mirror. Terminal choices are stored under terminal as the source of truth, then bridged to TERMINAL_* variables because terminal tools and child processes read those variables. The current working directory is resolved from the CLI process for local execution; remote and sandbox backends use their own workspace rules. Old MESSAGING_CWD and TERMINAL_CWD entries in .env are reported as deprecated so they do not silently override the YAML setting.

References: hermes_cli/config_env_routing.py• L1-15 hermes_cli/config_env_routing.py• L36-87 hermes_cli/cli_config_load.py• L121-165 hermes_cli/config.py• L2106-2134 hermes_cli/config.py• L1240-1260

Provider and model selection

Provider selection flow

Provider selection is shared by hermes setup model and hermes model. It shows the active model and provider, offers built-in and saved custom choices, runs the selected provider's credential flow, and saves the resulting model choice. The saved provider in model.provider takes precedence over the provider environment hint for normal chat startup; an explicit command choice takes precedence over both.

The selection flow supports provider-owned login, API-key setup, saved custom endpoints, and model catalog choice. A provider can be disabled in configuration, in which case it stays in the file but cannot be selected or used. Custom providers identify an endpoint and can also define a model list, protocol, credentials, and route-specific limits.

References: hermes_cli/main.py• L2030-2122 hermes_cli/runtime_provider.py• L490-499 hermes_cli/config_providers.py• L189-282 hermes_cli/config_providers.py• L604-615

Runtime route resolution

After setup saves a provider and model, runtime resolution turns that choice into one usable route. A route includes the provider, endpoint, credential source, model-specific protocol, and any provider-specific request data. The resolver prefers an explicit or named route, then matching credentials, OAuth or API-key access, and only then a generic OpenRouter or custom fallback.

The route must keep the endpoint, credential, and protocol together. Host and provider checks prevent a key for one service from being sent to another endpoint. A saved protocol is used only when it belongs to the selected provider; otherwise Hermes derives the protocol from the route and model.

This page covers the selection boundary. The model provider integration page explains request translation, credential pools, streaming, and recovery after a route has been built.

References: hermes_cli/runtime_provider.py• L994-1033 hermes_cli/runtime_provider.py• L1056-1098 hermes_cli/runtime_provider_backends.py• L116-199 hermes_cli/runtime_provider_custom.py• L522-590

Managed runtime setup

Terminal execution backends

The terminal backend defines where agent commands, file work, and code execution occur. Setup presents local execution, isolated containers, cloud sandboxes, SSH, and plugin-provided backends as one choice. Each backend carries its own isolation, persistence, credential, and workspace expectations.

Backend groupRuntime boundary
LocalRuns on the current machine and uses the selected working directory
Docker or SingularityRuns inside a configured image with resource and network controls
Modal, Daytona, or Vercel SandboxRuns in a cloud environment with provider-specific persistence
SSHRuns on a remote host through the configured connection
Plugin backendUses a registered backend with its own setup contract

Setup checks for required tools or SDKs and saves backend settings to the profile. It can also enable the Docker egress firewall, which gives sandbox traffic controlled proxy credentials instead of exposing the host's real API keys.

References: hermes_cli/setup_terminal.py• L126-163 hermes_cli/setup_terminal.py• L165-251 hermes_cli/setup_terminal.py• L254-325

Managed execution services

Some backends can use a managed service instead of the user's direct cloud account. When the Nous subscription and managed tool gateway are available, Modal setup can bind execution to the managed Nous route; otherwise it configures direct Modal credentials. The selected mode is saved so later runtime creation does not guess which account should pay for execution.

Cloud persistence is not uniform. Daytona keeps a dedicated persistent environment, while Vercel uses snapshots for files and does not keep live processes after sandbox recreation. These differences shape what a user can expect when a session starts again or a remote runtime is replaced.

References: hermes_cli/setup_terminal.py• L165-218 hermes_cli/config_defaults.py• L297-391

Managed configuration boundaries

Managed installations are controlled by an external package or system configuration. Local setup and ordinary config writes stop with a clear message instead of competing with that owner. The active profile still supplies runtime data within the allowed boundary, while managed values overlay user values at load time.

The same boundary applies to runtime services that need a profile home. A gateway or supervisor must receive the profile's home and service-user environment explicitly; an interactive shell's -p selection is not available to a process started with a clean service environment.

References: hermes_cli/config.py• L235-250 hermes_cli/config.py• L2456-2473 hermes_cli/config_home.py• L55-79 hermes_cli/main.py• L593-656

Change checklist

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

  • Keep the first-run readiness check aligned with provider authentication and model persistence. A new provider that the check cannot see will trigger setup on every launch.
  • Keep the three configuration loaders aligned with the surfaces that read them. A setting visible to the CLI but absent from the effective gateway view can produce different behavior by surface.
  • Keep every YAML setting that has an environment mirror synchronized in both directions. A stale .env value can silently change a child tool's runtime.
  • Keep migration steps safe for both stamped and unversioned files. New defaults should not become forced user choices, and legacy keys must not remain active after their replacement is read.
  • Keep provider identity, endpoint, credential source, and protocol selection together. Changing one without the others can route a valid key to the wrong service.
  • Keep managed overlays and managed runtime service environments outside local write paths. A local save must not erase administrator values or lose the profile boundary in a supervisor.

Important failure modes

TriggerConsequenceGuard
Setup runs without an interactive TTYThe process can block or exit while waiting for answersShow non-interactive guidance and stop before prompting
config.yaml contains invalid YAML before migrationRelated files could be changed while the main settings remain unreadableValidate the file before migration side effects and keep a recoverable copy
A stamped config is below the migration support floorAutomatic conversion could apply unsafe or obsolete assumptionsLeave the file unchanged and direct the user to backup and setup
A terminal setting remains only in .envA child tool can use a stale backend or working directoryTreat YAML as canonical and mirror supported terminal values deliberately
A provider switch leaves an old endpoint or protocolRequests can use the new model with the old route or wire formatMatch saved endpoint and mode to the selected provider before resolution
A managed install receives a local setup writeUser changes conflict with administrator-owned configurationRefuse local writes and report the managed owner
A cloud sandbox is recreatedFiles may persist while running processes disappearDescribe and configure persistence per backend rather than assuming one model

Key files

FileWhy to read it
hermes_cli/main.pyFirst-run readiness, profile selection, and shared provider/model entry point
hermes_cli/setup.pySetup wizard orchestration, modes, sections, backups, and completion flow
hermes_cli/setup_quick.pyPortal, quick, and blank-slate setup behavior
hermes_cli/setup_migration.pyOpenClaw preview, import confirmation, and post-import section handling
hermes_cli/config.pyProfile paths, merged loading, safe writes, managed restrictions, and migration entry point
hermes_cli/config_defaults.pyProduct defaults and the documented configuration shape
hermes_cli/config_effective.pyPresence-sensitive configuration view used by runtime surfaces
hermes_cli/config_env_routing.pyRules that route hermes config values to YAML or .env
hermes_cli/config_migrations.pyVersioned schema transformations and support-floor policy
hermes_cli/main.pyShared provider picker and model setup flows
hermes_cli/runtime_provider.pyFinal provider, endpoint, credential, and protocol resolution
hermes_cli/setup_terminal.pyTerminal backend and managed sandbox setup