NemoClaw Architecture Overview

This page explains how NemoClaw runs supported agent runtimes inside OpenShell sandboxes. It covers the host CLI, OpenShell gateway, agent integration layer, lifecycle state, managed Model Context Protocol (MCP) servers and other integrations, and protection layers.

NemoClaw does not replace OpenShell or the selected agent runtime. It packages them as a repeatable setup with a versioned blueprint, agent-specific configuration, managed inference, network policy, and lifecycle operations.

High-Level Flow

NemoClaw keeps operator control on the host while OpenShell enforces the sandbox boundary. The OpenShell gateway coordinates sandbox lifecycle, credentials, network policy, inference routes, and approved integration traffic.

The diagram has the following components:

For repository layout, file paths, and deeper diagrams, refer to Architecture.

Design Principles

NemoClaw follows these architecture principles.

Versioned blueprint : The blueprint runner resolves a versioned blueprint and verifies its digest before it changes managed resources.

Host credential custody : OpenShell stores inference provider credentials and managed MCP bearer values outside the sandbox and replaces placeholders at approved request boundaries.

Agent-specific integration : Each supported agent runtime receives the configuration, wrappers, plugin, or adapter required for its documented workflow.

Resumable lifecycle : NemoClaw records lifecycle progress and reconciles managed resources after supported interruptions or partial operations.

OpenShell-native state : Routine lifecycle operations keep the native home/workspace in OpenShell storage. Rebuild and recreation transfer that complete tree without a NemoClaw path allowlist; OpenShell-owned credential stores remain outside it.

CLI, Integration Layer, and Blueprint

NemoClaw separates host orchestration, agent-specific behavior, and sandbox definition.

• The host CLI runs readiness checks and onboarding, validates provider choices, records lifecycle state, and operates OpenShell resources.

• The Deep Agents integration layer writes managed runtime configuration under /sandbox/.deepagents. It includes config.toml, the agent-native .mcp.json, and the inference route used by dcode.

• The blueprint is a versioned YAML package with the sandbox image, agent manifest, network policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell.

This separation keeps host orchestration, agent-specific assets, and the sandbox definition at explicit lifecycle boundaries.

Inspect an External OpenShell Gateway

NemoClaw packages the experimental nemoclaw-blueprint-runner command for infrastructure that already owns an external OpenShell gateway. This path supports target planning and one credential-free public health request for OpenShell 0.0.116. It does not manage the gateway or establish support for another OpenShell release.

Create a blueprint directory with a blueprint.yaml file that contains one external target. The target must use a bare HTTPS origin, the exact OpenShell release, an absolute CA bundle path, and an absolute authentication file path. The CA bundle must be a nonempty regular file, must not be a symbolic link, and must be no larger than 1 MiB. The CA bundle must contain only PEM CA certificates. Both operations read the CA bundle. The plan requires a nonempty regular authentication file no larger than 1 MiB and inspects only its metadata. The status command does not access the authentication file. Neither operation creates or removes either administrator-owned file.

version: 1.0.0
min_openshell_version: 0.0.116
max_openshell_version: 0.0.116
openshell_target:
  endpoint: https://openshell.example.test:8443
  workspace: default
  expected_release: 0.0.116
  lifecycle: external
  trust:
    ca_file: /var/run/openshell-target/ca.pem
  authentication:
    credential_file: /var/run/openshell-target/authentication

Run the target-only plan when you need to validate the complete target configuration and print a sanitized plan. Planning requires the referenced authentication file, validates local input, fingerprints the CA bundle, and does not connect.

NEMOCLAW_BLUEPRINT_PATH=/absolute/path/to/blueprint nemoclaw-blueprint-runner plan

Run the external status command directly when you only need public health. Status requires the absolute authentication file reference but does not access the file. It makes one public health request through the official OpenShell SDK.

NEMOCLAW_BLUEPRINT_PATH=/absolute/path/to/blueprint nemoclaw-blueprint-runner status --external-target

A successful status result reports healthy, release 0.0.116, and compatible in JSON. The command does not access the authentication file or authenticate. The command supplies the validated CA bundle to the SDK and uses normal TLS hostname verification.

Readiness and Sandbox Creation

Run nemo-deepagents host probe when you need a read-only system readiness report before onboarding. The report combines host and gateway observations, capabilities, qualifications, findings, evidence, and CLI provenance without changing system state. Onboarding consumes the same stable host and gateway entities and applies its explicit admission policy. It revalidates live facts after permitted preparation and when a saved onboarding session resumes.

When you run nemo-deepagents onboard, the host CLI and blueprint runner complete these operations:

1. NemoClaw resolves gateway lifecycle authority and rejects blocking system readiness results before managed resource effects. A container-backed WSL GPU proof can run only after this admission check; explicit CPU-only intent skips it.
2. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest.
3. Onboarding validates the selected inference provider, credentials, agent settings, and platform requirements.
4. The runner determines which gateway, provider, policy, sandbox, and integration resources to create or update.
5. NemoClaw records progress so a supported interruption can resume or report a specific recovery action.

Before the blueprint runner writes a temporary policy update, it parses the merged live policy and refuses a literal credential value. Replace literal credentials with supported OpenShell credential bindings or resolver placeholders, then retry. The refusal happens before the policy file or OpenShell policy mutation is created.

After the sandbox starts, the selected agent uses its managed configuration and the controls supported by the host.

Lifecycle and State

NemoClaw operates the sandbox through host-side commands while OpenShell owns its persistent native home and workspace.

Refer to Recover and Rebuild Sandboxes and Persist Sandbox State for lifecycle details.

Inference Routing

Managed agent runtimes send model requests to inference.local instead of an upstream endpoint. During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell inference route, and writes the matching model reference into the managed agent configuration. OpenShell keeps the provider credential outside the sandbox and sends approved requests to the upstream endpoint. When you select the Model Router provider, inference.local routes to a host-side router that chooses from a configured model pool available through NVIDIA Endpoints for each request.

For Deep Agents, the managed dcode runtime reads the OpenAI-compatible route that NemoClaw writes into /sandbox/.deepagents/config.toml.

Managed Integrations

NemoClaw connects supported external services through OpenShell providers, network policy, and agent-specific adapters.

Managed MCP supports authenticated HTTPS Streamable HTTP MCP servers for OpenClaw, Hermes, and Deep Agents Code. NemoClaw stores the credential name and ownership metadata, while OpenShell stores the raw value outside the sandbox. The agent adapter receives a credential placeholder that OpenShell replaces only at the approved egress boundary.

Deep Agents Code can also opt into bounded trace export to an operator-managed host collector. Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside the sandbox. Refer to Understand Deep Agents Trace Export for the data and receiver trust boundaries.

Refer to About Managed MCP Servers for the managed MCP security and lifecycle design.

Protection Layers

The sandbox starts with a baseline policy that controls network egress, filesystem access, process privileges, and inference routing.

When the agent tries to reach an unapproved host, OpenShell blocks the request and surfaces it in the terminal user interface (TUI) for operator approval. Approved endpoints persist within the current sandbox instance but are not saved to the baseline policy file. NemoClaw’s runtime context tells supported agents to try allowed network and filesystem actions first, then report whether policy denial, DNS, timeout, TLS, or filesystem access caused a failure.

Host and platform limitations can change how individual controls apply. Refer to Platform Support and Security Best Practices before you treat a control as an environment-wide guarantee.

Next Steps

• Read Ecosystem for stack-level relationships and NemoClaw versus OpenShell-only paths.
• Follow Quickstart with Deep Agents to launch your first sandbox.
• Read Architecture for the full technical structure, including file layouts and the blueprint lifecycle.
• Read Choose an Inference Provider for detailed provider configuration.
• Read Network Policies for baseline rules and runtime changes.