Hermes Agent Deep Cuts: Gmail Has No Default Account
$ hermes connectors list
Connectors are not available. Sign in with `hermes login` first.
That is the actual output on this profile. The CLI is installed, but connector management is not a local account database you can inspect without Portal identity. Once signed in, the important operational detail is easy to miss: Hermes has no default connector account. Add a second Gmail login and every Gmail tool call must resolve to an account name, or fail.
The alias is a routing argument
A connector is a hosted app reached through the Nous Tool Gateway. Hermes keeps the account identity on the Portal side. The agent sees an alias such as home or work, and sends that alias as connector_alias when it calls a connector tool. The gateway resolves it to the matching account. The account ID is not the selector the model supplies.
That separation matters. The model chooses a human-readable route, while the service owns the underlying connection. The Tool Gateway documentation says that after an app has two or more active accounts, each tool for that app accepts connector_alias. If every account is named, the argument is required. If any account is unnamed, it can be omitted, but the model then has less explicit routing information.
The result reports the account name when the selected account is named. That gives an operator something to audit after a call: check which mailbox the tool actually used, not just whether it returned a plausible result.
Name accounts for explicit routing
Aliases are deliberately constrained: 1 to 32 characters, lowercase letters, digits, or hyphens, beginning with a letter or digit. A practical setup uses names that encode the boundary you care about, not the provider’s display label:
hermes connectors list
hermes connectors accounts
hermes connectors connect gmail --alias work
hermes connectors connect gmail --alias home
hermes connectors accounts gmail
Then make the route explicit in the request:
Search the work Gmail account for the latest invoice from Acme.
After connecting, the agent reports the chosen alias. To correct a name later:
hermes connectors rename gmail work --to finance
hermes connectors accounts gmail
The command grammar and account filters are in the CLI reference. The local command implementation validates aliases before sending them, and its selection logic requires --alias when multiple active accounts exist and no unique selection can be made.
Avoid aliases such as primary unless there really is an explicit policy behind them. Hermes does not interpret that word as a default. It is just another route label. A prompt that says “use my email” is ambiguous when there are several named accounts, and the system has no default account to rescue it.
Reconnect does not mean replace in place
A failed login has a non-obvious lifecycle. hermes connectors connect <app> --reconnect --alias <name> repairs a specific existing account. If the account is still active, Hermes stops and says it is already connected unless you pass --force. When it does reconnect, it replaces the connection under that alias and keeps the old record as retired. This preserves history without letting the retired account remain a live route.
hermes connectors connect gmail --reconnect --alias work
hermes connectors accounts gmail --all
If you use --force, it requests a new sign-in even for an active account. Treat that as account repair, not as a harmless refresh. The CLI selects the account by alias, then targets its connection ID for the repair operation. This is why --alias matters when an app has more than one account.
Removal is a different operation and requires confirmation. In a non-interactive shell, the command refuses to remove anything unless --yes is present:
hermes connectors disconnect gmail --alias home --yes
Do not put that command into a cleanup script that guesses the alias. It is a destructive choice, and --yes removes the only interactive confirmation gate.
The gotcha is the identity boundary
The local help text still points at hermes login, while the current CLI reference marks hermes login deprecated in favor of hermes auth. On this installed version, hermes auth has no login subcommand. hermes connectors itself prints the legacy hermes login instruction when Portal identity is absent. That mismatch is not a reason to try random sign-in commands: use the supported sign-in flow in your installed Hermes version, then retry the read-only list command.
There is another failure that can look like a connector bug: the CLI command and the agent’s connector tools depend on Portal identity and gateway availability. connectors_available() blocks the command before it reaches listing or account operations. A successful hermes connectors list proves only that the gateway supplied a connector catalog. It does not prove that the account you meant to use was selected on a later tool call.
Verify the route, not just the login
After connecting, inspect the account list and make sure the aliases are distinct:
hermes connectors accounts gmail
hermes connectors accounts gmail --all
Use --all when checking whether a failed reconnect left a retired row. The default hides retired accounts and prints only a count, so a clean-looking list is not proof that no old connection record exists.
For a real tool call, ask Hermes to use a specific alias and inspect the returned account field. If the answer does not identify the expected alias, stop before acting on the mailbox. The useful invariant is simple: every operation with multiple named accounts should have an explicit route in the request and a matching account in the result.
The account picker is not the security boundary by itself. The operator still has to phrase the request clearly, inspect which alias Hermes chose, and avoid destructive operations based on an ambiguous name. Hermes gives you explicit routes; it does not decide which person’s mailbox you meant.
Sources
- Nous Tool Gateway: Multiple connector accounts, account aliases,
connector_alias, retirement and result behavior. - Hermes CLI commands:
hermes connectors, supported command forms and options. hermes_cli/connectors_cmd.py, installed implementation of account listing, reconnect, alias validation, rename and disconnect.tools/connectors/managed.py, connector operation and account routing implementation.