Hermes Agent Deep Cuts: Safe Mode Is a Configuration Boundary, Not a Sandbox
Run hermes chat --safe-mode -q 'diagnostic probe' without a model and Hermes stops before opening a session: Error: --safe-mode / --ignore-user-config ... read no profile default: pass --model explicitly. The switch meant to get around a broken profile also drops the profile’s model choice.
The name overpromises. Safe mode isolates the session from Hermes customizations. It is not an operating-system sandbox for commands the agent can run.
What safe mode removes
The CLI reference says --safe-mode implies --ignore-user-config and --ignore-rules. The implementation takes those flags early, before the CLI reads user configuration. For the normal gateway-backed chat path, the client sends a safe-mode policy with session creation. The gateway freezes the explicit options and its code defaults into the session, then starts a managed worker for the turn.
That worker binds the policy before importing the agent runtime. In safe mode it does not read the profile. Hermes skips context files, memory, profile plugins, shell-hook registration, and MCP servers. A broken config.yaml therefore cannot prevent this troubleshooting path from starting. The relevant pieces are in gateway_chat.py, safe_worker_policy.py, and the managed worker bootstrap.
That is configuration isolation, not a security boundary around the host. The worker is a separate Hermes process with a frozen policy. The documentation does not describe it as a container, VM, or restricted operating-system account. If the selected built-in tools can access a file or execute a command, safe mode alone does not make that action harmless.
Start with explicit assumptions
A safe-mode launch cannot inherit the model from the profile, so specify one. For an OpenAI-compatible local endpoint, the documented form is:
export HERMES_LOCAL_KEY="your-endpoint-key"
hermes chat --safe-mode \
--provider custom \
--base-url http://127.0.0.1:8000/v1 \
--api-key "$HERMES_LOCAL_KEY" \
--model local \
-q "Is this failure caused by my Hermes profile?"
The endpoint must already be running and accept that model name. --api-key is a launch-only option for the custom provider. Hermes documents that it keeps the key in the running gateway’s memory for this session rather than writing it to disk. Do not put the literal key in shell history or a shared script. If the endpoint is local and does not require authentication, consult its API requirements rather than assuming an empty key will work.
For a hosted provider, use the provider’s exact model identifier and make sure the credential is available through the supported authentication path. --safe-mode bypasses profile configuration, so it cannot pick up a model or provider value that exists only there.
The launch policy is frozen when the session is created. Adding --safe-mode to a resume does not convert an existing ordinary session into a safe-mode session. Start a fresh session for the diagnostic, and do not assume a later profile edit changes its route.
The verification trap
This flag can produce a different Hermes environment, but it does not prove the problem is in your profile. Compare the same prompt and explicit route in a normal session and a fresh safe-mode session. If safe mode works, that narrows the search to something removed by the bypass, such as profile configuration, context files, plugins, hooks, memory, or MCP. It does not identify which one.
You can verify the most important behavior without making an inference from a successful answer:
hermes chat --safe-mode -q "diagnostic probe"
With no --model, the local CLI returns the explicit missing-model error before connecting to the gateway. Then verify the selected runtime with an actual request using a valid explicit model and provider. Confirm that the new session was created with the safe-mode policy, and test only in a disposable workspace if the request can invoke tools. A successful text answer does not show that terminal, file, or network access is contained.
This distinction matters when using safe mode to debug a customization failure. It gives you a cleaner baseline, not a safer place to run an untrusted task. For hostile code or data, keep the operating-system isolation and least-privilege controls in place. Use safe mode to take Hermes profile state out of the equation, then use the worker’s behavior and logs to narrow the cause.