DOCSEARCHbyAlgolia
Submit Docs

NVIDIA NemoClaw

repository·main·Indexed 12 days ago

https://github.com/nvidia/nemoclaw

An open-source reference stack for running AI agents safely within NVIDIA OpenShell sandboxes. NemoClaw provides managed inference, network policies, and lifecycle operations for supported agents including OpenClaw, Hermes, and LangChain Deep Agents Code. It includes a CLI for guided onboarding and a declarative Model-Specific Setup Registry to manage compatibility between AI models, providers, and agent runtimes.

Tokens
429.3K
Snippets
1.2K
Records
1.9K
Agent score
97%

What's inside NemoClaw

  1. Overview of the Inference library

    main

    The src/lib/inference module provides the foundational logic for managing AI model and provider configurations within NemoClaw. It is responsible for:

    • Configuration: Parsing and normalizing inference settings.
    • Health Monitoring: Performing health checks on inference endpoints.
    • Local Runtimes: Orchestrating local inference support (e.g., Ollama, vLLM).
    • Model Management: Providing helpers for model catalogs, including NVIDIA featured models, NIM (NVIDIA Inference Microservices) lifecycle support, and provider-specific model metadata.
    • Capabilities: Managing web-search capabilities and prompt/model display helpers.
    • Validation: Running onboarding-time inference validation probes.

  2. Overview of NVIDIA NemoClaw

    main

    NVIDIA NemoClaw is an open source reference stack designed to run supported AI agents safely inside NVIDIA OpenShell sandboxes.

    Key features include:

    • Guided Onboarding: A wizard-driven setup process.
    • Managed Inference: Controlled access to model inference.
    • Network Policy & Lifecycle Operations: Security and management for agent runtimes.
    • Credential Custody: OpenShell manages credentials for inference and host-configured integrations.

  3. Overview of PR Review Advisor

    main

    The PR Review Advisor is an SDK-powered, NemoClaw-specific pull request reviewer. It performs model-backed analysis within an OpenShell sandbox triggered from a trusted GitHub Actions job. It inspects PRs as read-only data and posts a single "sticky" comment to the PR containing blockers, warnings, and suggestions.

    Key review capabilities include:

    • Security & Workflow: Sandbox and workflow security reviews.
    • Acceptance Coverage: Checks against observable outcomes, constraints, non-goals, and supported contracts.
    • Codebase Integrity: Reviews codebase drift, architecture, and source-of-truth for fallback/recovery behaviors.
    • Testing & Quality: Static test-inventory context, E2E coverage analysis, and correctness checks that standard CI cannot prove.
    • Simplification: Identifies opportunities for safe deletes, YAGNI (You Ain't Gonna Need It) reductions, and shrinking.
    • Terminology: Semantic review of terms introduced or redefined in explanatory text, backed by repository evidence.

    Note: It does not report GitHub mergeability, branch protection, CI status, or E2E pass/fail status; these are handled by other PR UI elements.

  4. What is NVIDIA NemoClaw?

    main

    NVIDIA NemoClaw is an open-source reference stack designed to run AI agents (such as OpenClaw, Hermes, or LangChain Deep Agents Code) safely inside OpenShell sandboxes. It provides a structured way to manage the onboarding, lifecycle, and operations of these agents while enforcing security boundaries.

    NemoClaw consists of three primary components:

    1. Host CLI: For managing agent operations and lifecycle.
    2. Versioned Blueprint: To ensure repeatable and verified agent configurations.
    3. Agent-specific Integration Layer: Tailored support for different agent runtimes.

    The OpenShell gateway acts as the coordinator for sandbox lifecycle, managed inference, credentials, and policy enforcement.

  5. Use security helpers for redaction and credential management

    main

    The src/lib/security module provides reusable utility functions for handling sensitive data within the NemoClaw ecosystem. These helpers are designed for data processing and pattern matching, not for managing the lifecycle of credentials or user interaction.

    Available helper types:

    • Redaction: Tools for masking or removing sensitive information from logs or outputs.
    • Secret Patterns: Utilities for identifying sensitive strings (like API keys or tokens) using predefined patterns.
    • Credential Hashing: Functions for securely hashing credential data.
    • Credential Filtering: Helpers for filtering sensitive fields out of data structures.

    Important Architectural Constraint: Do not use these helpers for credential persistence or to trigger user prompts. Credential storage and management logic should be implemented within src/lib/credentials/** instead.

  6. Understand the Read-Only Boundary of `host probe`

    main

    The host probe command is strictly read-only and adheres to a security boundary:

    • No Mutation: It does not change the filesystem, services, Docker state, gateway, provider, credentials, or sandbox state.
    • Environment Isolation: Read-only child processes receive a restricted environment containing only:
      • Exact system variables
      • The selected OpenShell gateway
      • Validated local TLS directory (if present)
      • Supported local Unix Docker socket (if configured)
    • Credential Security: Ambient provider, OpenShell, sandbox, and gateway credentials are not forwarded to child processes.
    • Data Redaction: The public report redacts token-shaped values, credential-bearing URLs, process environments, and unrecognized fields. It also bounds the length of finding summaries and command evidence.

  7. How NemoClaw selects an Inference API

    main

    NemoClaw uses a probing mechanism during onboarding to determine which OpenAI-compatible endpoint to use. By default, it probes /v1/responses first to check for required streaming and tool-calling behavior. If the probe fails, it falls back to /v1/chat/completions.

    Important: Even if the /v1/responses probe succeeds, NemoClaw will still use /v1/chat/completions at runtime by default. This is a safety measure to prevent using local backends that might drop system prompts or tool definitions when receiving Responses API requests. You must explicitly set a preference to use the Responses API.

  8. Understand the NemoClaw Onboarding Journey Matrix

    main

    The onboarding lifecycle in NemoClaw is governed by a 'Journey Matrix' that defines how different operations (onboarding, refreshing, rebuilding, or rotating credentials) interact with the system state.

    Key lifecycle journeys include:

    • New Onboard: Uses onboard() and resolveOnboardEntryOptions to assemble policies, providers, and resource profiles. It establishes the initial sandbox and gateway settings.
    • --fresh Onboard: Uses resolveOnboardEntryOptions, prepareFreshSession, and createBaseImageResolutionContext. It disables auto-resume and forces base-image resolution, clearing prior sessions before starting a new one.
    • Resume, Re-onboard, or Recreate: Handles existing sandboxes. --resume uses recorded sessions as authoritative, while re-onboarding uses current flags as intent against existing registry/gateway state.
    • Rebuild or Upgrade: Uses rebuildSandbox or upgradeSandboxes. This is the primary path for repairing degraded state or applying updates via an installer.
    • Channel Management: Uses addSandboxChannel, removeSandboxChannel, and sandboxChannelsSetEnabled to manage messaging and policy deltas.
    • Credential Rotation: Uses configRotateToken to update provider bindings without deleting the sandbox.

    Understanding these journeys is critical for predicting whether an operation will be destructive (e.g., deleting a sandbox) or additive (e.g., updating a configuration).

  9. How Hooks architecture works

    main

    Hooks allow manifests to declare behavior using stable string identifiers without requiring direct imports of the underlying logic. A ChannelHookSpec in a manifest specifies a handler string, which the MessagingHookRegistry then maps to a concrete MessagingHookHandler.

    The execution flow is:

    1. The manifest declares a hook spec.
    2. The MessagingHookRegistry resolves the handler string.
    3. The runMessagingHook runner executes the handler.
    4. The handler produces validated outputs.
    5. These outputs are integrated into SandboxMessagingPlan entries.

    The runner enforces three invariants:

    • The handler ID must exist in the registry.
    • Required outputs declared by the manifest must be present.
    • Every output must use the declared output kind and be JSON-serializable.
    {
  id: "teams-host-forward-port-conflict",
  phase: "pre-enable",
  handler: "teams.hostForwardPortConflict",
  inputs: ["webhookPort"],
  onFailure: "abort",
}

  10. Restore user-owned state during Rebuild and Snapshot operations

    main

    In NemoClaw v0.0.81, rebuild and restore operations are designed to preserve user-owned state while preventing old backups from overwriting current managed configurations.

    Key behaviors include:

    • Agent Manifests: Can declare specific key-level restore ownership.
    • Managed Deep Agents: Restores are limited to allowlisted UI and thread preferences.
    • Hermes Rebuilds: Retain the Web Dashboard profile located at /sandbox/.hermes/dashboard-home/, which includes MEMORY.md and USER.md files.
    • Deep Agents Snapshotting: If ps is unavailable, the system falls back to /proc to attempt snapshot creation, but it will fail closed if it cannot verify the runtime is idle.

  11. Understand Advisory Signal Confidence and Actions

    main

    The early-warning correlation module emits structured signals with the following shape: {advisoryId, cveId?, package, vulnerableRange, matchedVersions, source, confidence, action}.

    Confidence is encoded based on the precision of the match rather than being inferred:

    • confidence: "exact" and action: "investigate": Occurs only when there is an exact match for the npm ecosystem, package name, and a parseable semantic-version range.
    • confidence: "ambiguous" and action: "informational": Occurs when name collisions arise from non-npm or CPE-derived records, or when ranges are unparseable. Ambiguous matches never block or mutate a release.

    The cveId field is optional and only appears if the advisory contains a well-formed cve_id.

  12. Understand policy preset persistence and rebuilds

    main

    NemoClaw records applied maintained presets and custom presets (including the full YAML content if applied via --from-file or --from-dir).

    When you run $$nemoclaw <name> rebuild, NemoClaw replays all recorded presets to the recreated sandbox. This ensures that even if the original custom preset files are deleted, the access is restored during a rebuild or snapshot restore.