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:
| Area | Product purpose |
|---|---|
| Model and provider | Choose the service and model that answer agent requests |
| Terminal backend | Choose where commands and code run |
| Messaging gateway | Connect chat platforms and make the gateway active |
| Tools | Enable tool groups and their credentials |
| Shared metrics | Decide whether bounded usage data stays local or is sent |
| Agent settings | Set 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:
| View | Purpose |
|---|---|
| CLI configuration | Merges CLI defaults with the user file and mirrors values needed by CLI tools |
| General configuration | Merges DEFAULT_CONFIG with the user file, environment references, and managed values |
| Effective user configuration | Preserves 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 group | Runtime boundary |
|---|---|
| Local | Runs on the current machine and uses the selected working directory |
| Docker or Singularity | Runs inside a configured image with resource and network controls |
| Modal, Daytona, or Vercel Sandbox | Runs in a cloud environment with provider-specific persistence |
| SSH | Runs on a remote host through the configured connection |
| Plugin backend | Uses 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
| Trigger | Consequence | Guard |
|---|---|---|
| Setup runs without an interactive TTY | The process can block or exit while waiting for answers | Show non-interactive guidance and stop before prompting |
| config.yaml contains invalid YAML before migration | Related files could be changed while the main settings remain unreadable | Validate the file before migration side effects and keep a recoverable copy |
| A stamped config is below the migration support floor | Automatic conversion could apply unsafe or obsolete assumptions | Leave the file unchanged and direct the user to backup and setup |
| A terminal setting remains only in .env | A child tool can use a stale backend or working directory | Treat YAML as canonical and mirror supported terminal values deliberately |
| A provider switch leaves an old endpoint or protocol | Requests can use the new model with the old route or wire format | Match saved endpoint and mode to the selected provider before resolution |
| A managed install receives a local setup write | User changes conflict with administrator-owned configuration | Refuse local writes and report the managed owner |
| A cloud sandbox is recreated | Files may persist while running processes disappear | Describe and configure persistence per backend rather than assuming one model |
Key files
| File | Why to read it |
|---|---|
| hermes_cli/main.py | First-run readiness, profile selection, and shared provider/model entry point |
| hermes_cli/setup.py | Setup wizard orchestration, modes, sections, backups, and completion flow |
| hermes_cli/setup_quick.py | Portal, quick, and blank-slate setup behavior |
| hermes_cli/setup_migration.py | OpenClaw preview, import confirmation, and post-import section handling |
| hermes_cli/config.py | Profile paths, merged loading, safe writes, managed restrictions, and migration entry point |
| hermes_cli/config_defaults.py | Product defaults and the documented configuration shape |
| hermes_cli/config_effective.py | Presence-sensitive configuration view used by runtime surfaces |
| hermes_cli/config_env_routing.py | Rules that route hermes config values to YAML or .env |
| hermes_cli/config_migrations.py | Versioned schema transformations and support-floor policy |
| hermes_cli/main.py | Shared provider picker and model setup flows |
| hermes_cli/runtime_provider.py | Final provider, endpoint, credential, and protocol resolution |
| hermes_cli/setup_terminal.py | Terminal backend and managed sandbox setup |