Security

Credential Storage

View as Markdown

NemoClaw does not persist provider credentials to host disk. The OpenShell gateway is the only system of record for stored credentials.

When you provide a provider credential, either interactively during nemo-deepagents 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.

NemoClaw manages Deep Agents Code provider credentials through the same OpenShell provider boundary. NemoClaw recreates generated Deep Agents runtime files during rebuilds. Those files should contain resolver placeholders or non-secret managed route values, not live provider credentials. For managed inference and MCP, NemoClaw keeps host-side auth in OpenShell providers and writes only managed configuration under /sandbox/.deepagents. The managed dcode launchers reject credential-shaped environment values and upstream auth state before Deep Agents Code starts. If /sandbox/.deepagents/.state/auth.json contains upstream credentials, or if /sandbox/.deepagents/.state/chatgpt-auth.json exists, the managed launchers refuse to start until you remove that credential state.

Where Credentials Live

Provider credentials live in the OpenShell gateway store. List registered provider names with:

$openshell provider list

Or use NemoClaw:

$nemo-deepagents credentials list

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.

Deep Agents supports the NemoClaw-managed Tavily opt-in path with TAVILY_API_KEY. NemoClaw does not enable Tavily by default for the managed dcode harness. NemoClaw registers the selected key in a sandbox-scoped provider named <sandbox>-brave-search or <sandbox>-tavily-search and writes openshell:resolve:env:<KEY> into the agent configuration.

For Deep Agents, the managed launch paths reject direct TAVILY_API_KEY injection into dcode. Register the key with OpenShell through nemo-deepagents credentials add tavily-search --type tavily --credential TAVILY_API_KEY, then apply the tavily policy preset and rebuild the sandbox so the provider attaches. The tavily preset is the sandbox-level network opt-in, while the tavily-search provider is gateway-wide and can attach to future sandboxes that you build or rebuild.

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 supports opt-in, backend-neutral OTLP tracing for the managed Deep Agents harness through an operator-run host collector. The sandbox sends traces only to the fixed local receiver and does not receive LANGSMITH_API_KEY, remote OTLP exporter headers, or backend credentials. Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside dcode. Keep backend credentials in the host collector, and refer to Export Traces Through a Local Collector for the supported setup.

NemoClaw still keeps non-secret operational state under ~/.nemoclaw/ (such as the sandbox registry). That directory is created with mode 0700 and contains no credential material.

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-... nemo-deepagents 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: nemo-deepagents <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 Set Up MCP Servers.

When the host environment is empty, day-two operations such as nemo-deepagents <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, nemo-deepagents <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 exactly 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 nemo-deepagents onboard or re-register the provider first.

Deploy Reads from Environment Only

nemo-deepagents deploy (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. A typical deploy invocation looks like:

$NVIDIA_INFERENCE_API_KEY=nvapi-... \
>    HF_TOKEN=hf_... \
>    TELEGRAM_BOT_TOKEN=... \
>    nemo-deepagents deploy my-instance

For remote vLLM or Hugging Face workflows that need gated model access, nemo-deepagents deploy also forwards HF_TOKEN and HUGGING_FACE_HUB_TOKEN to the VM when either variable is present. If a required credential is missing, deploy aborts before any remote work begins.

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 nemo-deepagents onboard after upgrading, NemoClaw automatically:

  1. Reads the legacy file.
  2. Stages allowlisted credential values into process.env for the rest of the run.
  3. Re-registers each value with the OpenShell gateway through the normal onboarding path.
  4. Securely overwrites and deletes ~/.nemoclaw/credentials.json only after every staged value has been verified as migrated to the gateway.

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 nemo-deepagents onboard to complete the verified gateway migration and cleanup.

Rotate or Remove a Stored Credential

To replace a stored value, rerun onboarding with the new value in your environment:

$NVIDIA_INFERENCE_API_KEY=nvapi-new-value nemo-deepagents onboard

To remove a credential from the gateway entirely:

$nemo-deepagents credentials reset <PROVIDER_NAME>

<PROVIDER_NAME> is the OpenShell provider name (run nemo-deepagents 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

  1. Prefer short-lived or low-scope provider credentials where the upstream service supports them.
  2. Rotate keys after suspected exposure, machine transfer, or account changes.
  3. Prefer environment variables for ephemeral automation rather than registering long-lived secrets in the gateway.
  4. Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. Credentials no longer live on disk, but surrounding configuration may reveal which providers you have registered.
  5. Keep your home directory private and owned by your user account.

For the broader sandbox security model and operational trade-offs, refer to Security Best Practices, Workspace Files, and Set Up MCP Servers.