Credential Storage
NemoClaw registers newly supplied provider credentials directly with the OpenShell gateway. It does not create a plaintext host credential store. The OpenShell gateway is the system of record for stored provider credentials. Upgrades can retain earlier plaintext entries until their migration is verified, as described below.
When you provide a provider credential, either interactively during nemohermes onboard or with an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through openshell provider create or openshell provider update.
The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret.
Before direct sandbox creation, NemoClaw verifies attached NemoClaw-owned provider profiles. After a verified direct creation, it warns if a profile changed or verification did not complete. The sandbox remains created because NemoClaw cannot determine which profile definition OpenShell used during attachment. Ask the gateway operator to inspect the profile before relying on its credential boundary.
NemoClaw manages Hermes API credentials and provider credentials through the same OpenShell provider boundary.
NemoClaw recreates generated Hermes runtime files during rebuilds.
Those files should contain resolver placeholders, not live provider credentials.
For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into /sandbox/.hermes/config.yaml, /sandbox/.hermes/.env, and process environment entries visible to the sandbox.
For OAuth-backed managed tools, NemoClaw imports an endpointless tool-gateway profile and stores an opaque broker token in its OpenShell provider.
The host broker keeps the OAuth refresh token in memory and persists only its digest in host state.
NemoClaw verifies the profile and the provider’s non-secret binding before it creates or reuses that provider.
It updates a compatible legacy provider in place.
If the profile or provider binding does not match, onboarding stops before it changes inference.
Ask the gateway operator to inspect the profile and provider attachments before retrying.
Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces.
The managed Hermes wrapper reads that token from /sandbox/.hermes/.env and supplies it only through the dashboard process environment.
For inference.local, Hermes stores the OpenShell proxy rewrite sentinel in its native inference configuration.
Generated NVIDIA Build configuration uses ${NVIDIA_INFERENCE_API_KEY} for supervisor expansion.
A live switch to NVIDIA Build writes the newly attached provider’s scoped OpenShell credential reference into the native configuration.
These values do not expose the raw provider credential.
Where Credentials Live
Provider credentials live in the OpenShell gateway store. List registered provider names with:
Or use NemoClaw:
Both commands show the provider names registered with the gateway. The CLI cannot read the values back. OpenShell deliberately preserves this property.
Web Search Credentials
Web search follows the same OpenShell provider boundary as inference and messaging credentials.
Hermes supports TAVILY_API_KEY.
During onboarding, NemoClaw registers the selected key in an OpenShell provider named <sandbox>-tavily-search.
OpenShell supplies TAVILY_API_KEY through the Hermes process environment as a revision-scoped reference such as openshell:resolve:env:v<revision>_TAVILY_API_KEY.
NemoClaw omits this key from the generated gateway and dashboard .env files so Hermes cannot overwrite the current reference with an unversioned or stale saved value.
Do not copy a Tavily reference or raw key into those files, and do not invent or reuse a revision from an older provider.
During onboarding, NemoClaw also checks the live sandbox environment for the raw selected web search credential.
If the raw key is visible there, or if the sandbox does not return a valid isolation result, onboarding refuses to report the sandbox as ready.
Retry onboarding after checking sandbox health; recreate the sandbox if the isolation check still fails.
Hermes sends its Tavily placeholder in the JSON api_key field.
The tavily policy preset enables request-body credential rewriting so OpenShell replaces that body value at egress without exposing the raw key to Hermes.
Use a dedicated low-scope search key and keep the matching brave or tavily policy preset applied only while the sandbox needs web search.
Rerun onboarding when you change providers because the provider selection and credential attachment are part of the sandbox image.
NemoClaw still keeps non-secret operational state under ~/.nemoclaw/ (such as the sandbox registry).
That directory is created with mode 0700. An upgraded installation can retain the legacy file described below until its values are migrated or removed.
Environment Variables Take Precedence
When a NemoClaw command needs a credential value during a single run (for example to forward it to an openshell provider registration), it reads from process.env first.
Use this precedence to:
- Prefix any command with the credential to override the gateway-stored value:
NVIDIA_INFERENCE_API_KEY=nvapi-... nemohermes onboard. - Use short-lived or rotated credentials in CI by exporting them once per pipeline run.
- Avoid registering credentials in the gateway entirely if the specific command supports environment-only use.
Managed MCP is an exception: nemohermes <name> mcp add always creates and attaches an OpenShell provider, and --env KEY supplies only the transient input value.
For that credential boundary, refer to About Managed MCP Servers.
Before an ordinary live-sandbox rebuild or forced host-side recovery changes managed MCP state, NemoClaw compares the credential keys for every provider attached to the sandbox.
If another provider supplies a credential key that a managed MCP server reserves, rebuild stops before it changes the managed provider attachment, generated policy, or agent adapter.
The collision check does not delete either provider or its stored credential value.
Forced host-side recovery repeats the check before sandbox deletion.
Detach only the conflicting provider from the affected sandbox:
This command keeps the provider and stored credential in OpenShell and does not change its attachments to other sandboxes.
Rerun the original rebuild command.
Do not run nemohermes credentials reset <PROVIDER_NAME> unless you intend to detach that provider from every sandbox and delete its stored credential from OpenShell.
When the host environment is empty, day-two operations such as nemohermes <name> rebuild and remote-provider updates can reuse the credential already registered with the OpenShell gateway.
Export the credential only when you want to create, replace, or rotate the stored provider value.
On the standard remote-provider path, an ordinary rebuild still requires the matching OpenShell provider entry.
If the sandbox registry points at one of these providers that is missing from OpenShell, nemohermes <name> rebuild stops before backup or delete even when you export the matching credential environment variable.
After a gateway replacement, the installer’s validated prepared-backup recovery can make a narrow exception.
It can recreate a missing provider only when the provider name and credential variable match NemoClaw’s built-in remote-provider mapping and the mapped variable resolves to a nonempty value in the current host process.
A missing credential or a provider-to-credential mismatch stops recovery before backup or delete.
For any other missing-provider case, rerun nemohermes onboard or re-register the provider first.
Onboarding Reads Credentials from Environment
nemohermes onboard reads credentials from the host environment, registers them with the OpenShell gateway, and creates the sandbox.
A typical onboarding invocation looks like:
GitHub Tokens
NemoClaw never persists GITHUB_TOKEN itself.
When a private repo requires authentication, NemoClaw runs gh auth token, which returns whatever the GitHub CLI has stored.
NemoClaw does not depend on the storage backend.
The GitHub CLI prefers an OS keychain when one is reachable: macOS Keychain on macOS, Windows Credential Manager on Windows, and Linux Secret Service (libsecret + a running D-Bus session) on Linux.
On hosts where no keychain is reachable, such as CI runners, headless launches, WSL without a session bus, or macOS contexts where Keychain access is blocked, gh auth login falls back to a gh-managed file under ~/.config/gh/ with mode 0600.
NemoClaw treats both backends identically.
gh auth token returns the value, and NemoClaw stages it in process.env for the current run only.
If gh is not installed or not logged in, NemoClaw prompts for a personal access token for that single run; the prompted value is held in process memory and is not written to host disk.
Run gh auth login if you want a persistent backing store (whichever one applies on your host) so future runs do not prompt.
Migration From Earlier Releases
Earlier NemoClaw releases stored credentials as plaintext JSON in ~/.nemoclaw/credentials.json with mode 0600.
On first nemohermes onboard after upgrading, NemoClaw automatically:
- Reads the legacy file.
- Stages allowlisted credential values into
process.envfor the rest of the run. - Re-registers each value with the OpenShell gateway through the normal onboarding path.
- After every staged value has been verified as migrated, removes only entries whose current values still match that verified migration.
Unknown entries, unstaged entries, and values changed before cleanup reads the file remain in the legacy file.
Avoid editing the legacy file while onboarding is running; cleanup detects observed changes but does not lock out concurrent writers.
NemoClaw replaces a mixed file atomically with mode 0600; the temporary file contains only retained entries.
Failures before replacement leave the original file intact. A reported durability or cleanup failure after replacement requires inspecting the retained file before retrying.
When no entries remain, NemoClaw securely overwrites and deletes the file.
This cleanup does not create or update stored provider credentials; the OpenShell gateway remains their system of record.
You see a one-line stderr notice the first time this happens.
Credential lookup paths such as rebuild also stage allowlisted legacy values so interrupted upgrades can keep working, but those staging-only paths do not delete the plaintext file because they cannot prove every legacy value was registered with the gateway.
If ~/.nemoclaw/credentials.json remains after a rebuild or other credential lookup, run nemohermes onboard to complete the verified gateway migration and cleanup.
Onboarding also sweeps a leftover ~/.nemoclaw/credentials.json that holds nothing to migrate, such as an empty file, an empty {}, or entries whose values are all blank.
The sweep keeps files with non-blank strings or non-string values, including entries that NemoClaw does not recognize.
Rotate or Remove a Stored Credential
To replace a stored value, rerun onboarding with the new value in your environment:
To remove a credential from the gateway entirely:
<PROVIDER_NAME> is the OpenShell provider name (run nemohermes credentials list first if you are not sure).
On the next run NemoClaw prompts again unless the credential is supplied through the environment.
Security Recommendations
- Prefer short-lived or low-scope provider credentials where the upstream service supports them.
- Rotate keys after suspected exposure, machine transfer, or account changes.
- Prefer environment variables for ephemeral automation rather than registering long-lived secrets in the gateway.
- Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. An upgraded installation can retain unmigrated legacy entries. Other configuration can reveal which providers you have registered.
- Keep your home directory private and owned by your user account.
Related Files
For the broader sandbox security model and operational trade-offs, refer to Security Best Practices, Architecture, and About Managed MCP Servers.