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.

Manifest-declared state : Rebuild, snapshot, and restore operations preserve only the state declared for the selected agent runtime. Each agent manifest and operation defines which credential-bearing files to exclude.

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, managed MCP projection state, 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.

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.

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 and its manifest-declared state through host-side commands.

Refer to Recover and Rebuild Sandboxes and Create and Restore Snapshots 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 the configured NVIDIA model pool 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.