Security

Credential Rotation

View as Markdown

NemoClaw uses different rotation paths for inference, messaging, and web search credentials. Inference credentials can normally be updated while reusing the existing sandbox. For an active Telegram, Discord, Slack, WeChat, or Microsoft Teams channel, onboarding runs the configured checks for a supplied replacement credential before it backs up supported workspace and manifest-declared state, recreates the sandbox, and restores the backup. Some channels cannot prove that a non-empty credential is valid until the recreated runtime connects, so complete the post-recreation verification on this page before treating the rotation as successful. Files outside those state paths are not preserved. Web search settings require recreation because their configuration is applied when the sandbox image starts.

Before You Start

List the provider names registered with the OpenShell gateway.

$nemohermes credentials list

The output is authoritative for commands that accept an OpenShell provider name. An inference provider is commonly named nvidia-prod, while an onboarded web search provider is commonly named <sandbox>-brave-search or <sandbox>-tavily-search. Provider names can differ with your selected inference route and sandbox configuration.

Per-sandbox messaging bridge names are not resettable credentials. Use the onboarding rotation flow below to replace an active messaging credential. Use channels add, channels remove, or channels stop to manage integrations instead of passing a bridge name to credentials reset.

CredentialSupported rotation pathSandbox impact
Inference API keyRerun onboarding with the replacement valueThe existing sandbox can normally be reused unless onboarding detects unrelated configuration drift
Active Telegram, Discord, Slack, WeChat, or Microsoft Teams credentialRerun onboarding with the replacement valueOnboarding applies the messaging rotation procedure, which recreates the sandbox. Some channels require verification after recreation.
Brave or Tavily web search keyRerun onboarding with the selected web search providerSandbox recreation required

Rotate an Inference API key

Supply the replacement key and rerun onboarding for the existing sandbox. Read replacement credentials silently on a trusted host so their values do not enter shell history or terminal scrollback. Unset each variable after the command finishes.

$printf 'New NVIDIA inference API key: ' >&2
$IFS= read -r -s NVIDIA_INFERENCE_API_KEY
$printf '\n' >&2
$export NVIDIA_INFERENCE_API_KEY
$nemohermes onboard --name <sandbox> \
>  --non-interactive --yes --yes-i-accept-third-party-software
$unset NVIDIA_INFERENCE_API_KEY

Onboarding updates the selected OpenShell inference provider and reuses the sandbox when its recorded configuration is still compatible. If onboarding detects other configuration drift, review the requested rebuild or recreation before continuing.

For an interactive rotation, export the replacement key and run nemohermes onboard --name <sandbox> without the non-interactive flags.

Rotate a Messaging Credential

Supply the replacement credential and rerun onboarding for the existing sandbox.

Understand the Recreation Boundary

For each supported active-channel credential that you supply, NemoClaw compares the replacement with the SHA-256 hash in the sandbox registry. NemoClaw runs each changed value through the checks configured for that channel before it backs up or replaces the sandbox. It then backs up supported workspace and manifest-declared state, destroys and recreates the sandbox, and restores the backup. Files outside those state paths are not preserved. If an available pre-recreation check fails, onboarding leaves the existing sandbox unchanged. Discord and Microsoft Teams require non-empty replacement input but cannot prove upstream credential validity before recreation. For those channels, an invalid non-empty replacement can surface only after recreation, so verify a live messaging request after onboarding finishes. If the recorded channel state changes during rotation, onboarding stops before it replaces the sandbox. Rerun onboarding so it uses the updated channel state.

Understand Credential Handling

Onboarding reads the replacement from the host environment and registers it with the sandbox-specific OpenShell messaging provider. The sandbox registry stores the credential hash, not the credential value. The unset command in each procedure removes the value from the current host shell after onboarding. OpenShell retains the registered credential until a later rotation or channel removal replaces or removes it.

A channel stopped with channels stop remains inactive, and its replacement environment variable does not trigger recreation. Run nemohermes <sandbox> channels start <channel> before this rotation procedure when you intend to activate the replacement credential.

Slack

Slack requires both replacement tokens.

$printf 'New Slack bot token: ' >&2
$IFS= read -r -s SLACK_BOT_TOKEN
$printf '\n' >&2
$printf 'New Slack app token: ' >&2
$IFS= read -r -s SLACK_APP_TOKEN
$printf '\n' >&2
$export SLACK_BOT_TOKEN SLACK_APP_TOKEN
$nemohermes onboard --name <sandbox> \
>  --non-interactive --yes --yes-i-accept-third-party-software
$unset SLACK_BOT_TOKEN SLACK_APP_TOKEN

Telegram

$printf 'New Telegram bot token: ' >&2
$IFS= read -r -s TELEGRAM_BOT_TOKEN
$printf '\n' >&2
$export TELEGRAM_BOT_TOKEN
$nemohermes onboard --name <sandbox> \
>  --non-interactive --yes --yes-i-accept-third-party-software
$unset TELEGRAM_BOT_TOKEN

Discord

$printf 'New Discord bot token: ' >&2
$IFS= read -r -s DISCORD_BOT_TOKEN
$printf '\n' >&2
$export DISCORD_BOT_TOKEN
$nemohermes onboard --name <sandbox> \
>  --non-interactive --yes --yes-i-accept-third-party-software
$unset DISCORD_BOT_TOKEN

The same onboarding flow evaluates active WECHAT_BOT_TOKEN and MSTEAMS_APP_PASSWORD bindings. Supply the replacement credential together with any required channel configuration. Rerun onboarding interactively when the channel uses a guided credential flow such as WeChat pairing.

For other channels add management, run the command from a terminal and omit NEMOCLAW_NON_INTERACTIVE=1 and token variables to be prompted for values and offered an interactive rebuild. A session without a terminal on stdin fails fast on a missing token instead of prompting for it. When token variables are set, that session queues the change for a manual rebuild.

Rotate a Web Search Key

Web search provider configuration and credential attachment are baked into the sandbox image. Select the provider again and recreate the sandbox so the replacement becomes active.

Hermes uses Tavily for NemoClaw-managed web search. Brave is not a supported Hermes web search backend.

$printf 'New Tavily API key: ' >&2
$IFS= read -r -s TAVILY_API_KEY
$printf '\n' >&2
$export TAVILY_API_KEY
$NEMOCLAW_WEB_SEARCH_PROVIDER=tavily \
>  nemohermes onboard --fresh --name <sandbox> --recreate-sandbox \
>  --non-interactive --yes --yes-i-accept-third-party-software
$unset TAVILY_API_KEY

Remove and Re-register a Provider Credential

Use credentials reset only when you need to remove an inference or web search provider before its replacement is available. Run nemohermes credentials list first, then pass the exact provider name from that output.

$nemohermes credentials reset nvidia-prod --yes

Removing a provider interrupts requests that depend on it. Re-register an inference provider with the inference rotation command above. For web search, repeat the matching web search onboarding flow and recreate the sandbox.

Do not pass a messaging bridge name to credentials reset. Use the messaging rotation flow above to replace a credential, or nemohermes <sandbox> channels remove <channel> to retire the integration.

Emergency Rotation After Key Compromise

If a credential was exposed, act in this order:

  1. Revoke the exposed credential at the upstream provider before relying on any local cleanup.

  2. For inference or web search, remove the exact provider shown by nemohermes credentials list if a replacement is not immediately available.

  3. For messaging, use channels remove to retire the integration or rerun onboarding with the replacement credential so NemoClaw runs the channel’s configured checks before automatic recreation.

  4. Issue a replacement credential at the upstream provider.

  5. Follow the matching rotation procedure on this page.

  6. Complete a real request through the affected inference, search, or messaging integration.

  7. Review recent sandbox logs for unexpected authentication failures or use of the retired credential:

    $nemohermes <sandbox> logs --since 24h | grep -i "auth\|401\|403\|forbidden"

Rotate an Inference Key in CI/CD

Supply credentials through the CI system’s secret store and inject them as environment variables. Non-interactive onboarding must include the third-party software acceptance flag.

1- name: Rotate inference key
2  env:
3    NVIDIA_INFERENCE_API_KEY: ${{ secrets.NVIDIA_INFERENCE_API_KEY }}
4  run: >-
5    nemohermes onboard --name <sandbox>
6    --non-interactive --yes --yes-i-accept-third-party-software

Do not commit credential values or host-side NemoClaw state to the repository. Plan for recreation downtime when automating messaging or web search rotation.

Verify the Replacement

nemohermes credentials list confirms that a provider exists, but it does not reveal or validate the stored value. nemohermes status performs host-side reachability checks without sending cloud API keys, so even an HTTP 401 or 403 can count as reachable there. nemohermes <name> status also sends one inference request through the stored provider credential and reports unauthorized when the route rejects it with HTTP 401 or 403. nemohermes inference get reports the active route and does not authenticate a model request.

Complete a real request through the rotated integration before declaring the rotation successful.

Verify an inference key by forwarding the Hermes API and making a chat-completions request with the onboarded model.

A Hermes sandbox can serve its OpenAI-compatible API on a port other than 8642. A sandbox uses 8642 when no other sandbox or host listener already holds it. Run openshell forward list and find the rows for <sandbox>. Select the row whose port is from 8642 through 8652, not the dashboard row. Replace <api-port> below with that API port.

$TOKEN=$(nemohermes <sandbox> gateway-token --quiet)
$openshell forward start --background <api-port> <sandbox>
$curl -sN http://127.0.0.1:<api-port>/v1/chat/completions \
>  -H 'Content-Type: application/json' \
>  -H "Authorization: Bearer $TOKEN" \
>  -d '{"model":"<onboarded-model>","messages":[{"role":"user","content":"Reply with credential-check-ok"}],"stream":false}'

To verify messaging, send a test message from an allowed account and confirm the sandbox receives it and responds. To verify web search, ask the agent to perform a search and confirm that the tool returns current results without an authentication error.