# nvidia/nemoclaw architecture

> Architecture diagram of the GitHub repository nvidia/nemoclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/nemoclaw
- Repository: https://github.com/nvidia/nemoclaw

## Overview

NemoClaw is a CLI reference stack for running supported AI agents inside OpenShell sandboxes. The principal workflow is: an operator invokes the CLI, onboarding selects an agent and inference provider, NemoClaw builds policy and runtime configuration, launches or rebuilds a sandbox, and the agent produces results through managed inference and integrations. The graph preserves lifecycle, snapshots, networking, messaging, MCP, and voice branches. Some subsystem links are documented or inferred only from directory structure; sampled source chiefly confirms orchestration, storage, policy, and runtime-adapter boundaries.

Main entry points: [`src/commands/onboard.ts`](https://github.com/nvidia/nemoclaw/blob/main/src/commands/onboard.ts) (Onboarding), [`src/lib/onboard/runtime-provider/host-local-inference-routing.ts`](https://github.com/nvidia/nemoclaw/blob/main/src/lib/onboard/runtime-provider/host-local-inference-routing.ts) (Inference Routing), [`src/lib/adapters/container-engine.ts`](https://github.com/nvidia/nemoclaw/blob/main/src/lib/adapters/container-engine.ts) (Container Engine), [`src/lib/actions/sandbox/rebuild-pipeline.ts`](https://github.com/nvidia/nemoclaw/blob/main/src/lib/actions/sandbox/rebuild-pipeline.ts) (Rebuild Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Onboarding"]
  node_cli_entry["NemoClaw CLI"]
  node_onboard["Onboarding<br/>[onboard.ts]"]
  node_agent_defs["Agent Definitions<br/>[agent-defs.js]"]
end

subgraph group_sandbox["Sandbox Lifecycle"]
  node_sandbox_actions["Sandbox Actions<br/>[launch.ts]"]
  node_rebuild["Rebuild Pipeline"]
  node_snapshots["Snapshot Management"]
  node_blueprint_runner["Blueprint Runner<br/>[runner.ts]"]
  node_container_engine["Container Engine"]
end

subgraph group_security["Security and State"]
  node_policy["Network Policy"]
  node_state_authority[("Runtime Authority")]
  node_mcp_lock[("MCP Lifecycle Lock")]
end

subgraph group_inference["Inference and Agents"]
  node_inference_routing["Inference Routing"]
  node_vllm_storage["Model Storage Checks<br/>[vllm-storage.ts]"]
  node_agent_profiles["Supported Agent Profiles"]
end

subgraph group_integrations["Managed Integrations"]
  node_messaging_render["Messaging Rendering"]
  node_messaging_build["Messaging Build Plan"]
  node_voice_sessions["Voice Sessions<br/>[session-service.ts]"]
end

node_operator(("Operator"))
node_openshell{{"OpenShell"}}
node_providers{{"Inference Providers"}}
node_agent_runtime["Agent Runtime"]
node_external_channels{{"Messaging Channels"}}

node_operator -->|"invokes CLI"| node_cli_entry
node_cli_entry -->|"dispatches"| node_onboard
node_onboard -->|"selects agent"| node_agent_defs
node_onboard -->|"configures inference"| node_inference_routing
node_onboard -->|"starts sandbox"| node_sandbox_actions
node_agent_defs -->|"resolves profile"| node_agent_profiles
node_sandbox_actions -->|"runs blueprint"| node_blueprint_runner
node_sandbox_actions -->|"controls runtime"| node_container_engine
node_blueprint_runner -->|"uses sandbox"| node_openshell
node_rebuild -->|"recreates runtime"| node_container_engine
node_rebuild -->|"restores state"| node_snapshots
node_rebuild -->|"coordinates lifecycle"| node_mcp_lock
node_snapshots -->|"persists authority"| node_state_authority
node_policy -->|"applies policy"| node_openshell
node_container_engine -->|"runs containers"| node_openshell
node_inference_routing -->|"routes requests"| node_providers
node_inference_routing -->|"verifies authority"| node_state_authority
node_vllm_storage -->|"probes storage"| node_container_engine
node_agent_runtime -->|"requests inference"| node_inference_routing
node_agent_runtime -->|"renders channels"| node_messaging_render
node_messaging_render -->|"configures channels"| node_external_channels
node_messaging_build -->|"builds integration"| node_agent_runtime
node_voice_sessions -.->|"forwards turns"| node_agent_runtime
node_agent_runtime -.->|"exchanges messages"| node_external_channels

click node_onboard "https://github.com/nvidia/nemoclaw/blob/main/src/commands/onboard.ts"
click node_agent_defs "https://github.com/nvidia/nemoclaw/blob/main/bin/lib/agent-defs.js"
click node_sandbox_actions "https://github.com/nvidia/nemoclaw/blob/main/src/lib/actions/sandbox/launch.ts"
click node_rebuild "https://github.com/nvidia/nemoclaw/blob/main/src/lib/actions/sandbox/rebuild-pipeline.ts"
click node_snapshots "https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/snapshot-management.ts"
click node_blueprint_runner "https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/runner.ts"
click node_container_engine "https://github.com/nvidia/nemoclaw/blob/main/src/lib/adapters/container-engine.ts"
click node_policy "https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/openshell-policy.ts"
click node_state_authority "https://github.com/nvidia/nemoclaw/blob/main/src/lib/onboard/runtime-provider/persisted-engine-authority.ts"
click node_mcp_lock "https://github.com/nvidia/nemoclaw/blob/main/src/lib/state/mcp-lifecycle-lock-storage.ts"
click node_inference_routing "https://github.com/nvidia/nemoclaw/blob/main/src/lib/onboard/runtime-provider/host-local-inference-routing.ts"
click node_vllm_storage "https://github.com/nvidia/nemoclaw/blob/main/src/lib/inference/vllm-storage.ts"
click node_agent_profiles "https://github.com/nvidia/nemoclaw/tree/main/agents"
click node_messaging_render "https://github.com/nvidia/nemoclaw/blob/main/src/lib/messaging/compiler/engines/agent-render-engine.ts"
click node_messaging_build "https://github.com/nvidia/nemoclaw/blob/main/src/lib/messaging/compiler/engines/build-step-engine.ts"
click node_voice_sessions "https://github.com/nvidia/nemoclaw/blob/main/src/lib/voice-gateway/session-service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_onboard,node_agent_defs toneBlue
class node_sandbox_actions,node_rebuild,node_snapshots,node_blueprint_runner,node_container_engine toneAmber
class node_policy,node_state_authority,node_mcp_lock toneMint
class node_inference_routing,node_vllm_storage,node_agent_profiles toneRose
class node_messaging_render,node_messaging_build,node_voice_sessions,node_operator,node_openshell,node_providers,node_agent_runtime,node_external_channels toneIndigo
```

## Components

### CLI and Onboarding

- **NemoClaw CLI**
- [Onboarding](https://github.com/nvidia/nemoclaw/blob/main/src/commands/onboard.ts): `src/commands/onboard.ts`
- [Agent Definitions](https://github.com/nvidia/nemoclaw/blob/main/bin/lib/agent-defs.js): `bin/lib/agent-defs.js`

### Sandbox Lifecycle

- [Sandbox Actions](https://github.com/nvidia/nemoclaw/blob/main/src/lib/actions/sandbox/launch.ts): `src/lib/actions/sandbox/launch.ts`
- [Rebuild Pipeline](https://github.com/nvidia/nemoclaw/blob/main/src/lib/actions/sandbox/rebuild-pipeline.ts): `src/lib/actions/sandbox/rebuild-pipeline.ts`
- [Snapshot Management](https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/snapshot-management.ts): `nemoclaw/src/blueprint/snapshot-management.ts`
- [Blueprint Runner](https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/runner.ts): `nemoclaw/src/blueprint/runner.ts`
- [Container Engine](https://github.com/nvidia/nemoclaw/blob/main/src/lib/adapters/container-engine.ts): `src/lib/adapters/container-engine.ts`

### Security and State

- [Network Policy](https://github.com/nvidia/nemoclaw/blob/main/nemoclaw/src/blueprint/openshell-policy.ts): `nemoclaw/src/blueprint/openshell-policy.ts`
- [Runtime Authority](https://github.com/nvidia/nemoclaw/blob/main/src/lib/onboard/runtime-provider/persisted-engine-authority.ts): `src/lib/onboard/runtime-provider/persisted-engine-authority.ts`
- [MCP Lifecycle Lock](https://github.com/nvidia/nemoclaw/blob/main/src/lib/state/mcp-lifecycle-lock-storage.ts): `src/lib/state/mcp-lifecycle-lock-storage.ts`

### Inference and Agents

- [Inference Routing](https://github.com/nvidia/nemoclaw/blob/main/src/lib/onboard/runtime-provider/host-local-inference-routing.ts): `src/lib/onboard/runtime-provider/host-local-inference-routing.ts`
- [Model Storage Checks](https://github.com/nvidia/nemoclaw/blob/main/src/lib/inference/vllm-storage.ts): `src/lib/inference/vllm-storage.ts`
- [Supported Agent Profiles](https://github.com/nvidia/nemoclaw/tree/main/agents): `agents`

### Managed Integrations

- [Messaging Rendering](https://github.com/nvidia/nemoclaw/blob/main/src/lib/messaging/compiler/engines/agent-render-engine.ts): `src/lib/messaging/compiler/engines/agent-render-engine.ts`
- [Messaging Build Plan](https://github.com/nvidia/nemoclaw/blob/main/src/lib/messaging/compiler/engines/build-step-engine.ts): `src/lib/messaging/compiler/engines/build-step-engine.ts`
- [Voice Sessions](https://github.com/nvidia/nemoclaw/blob/main/src/lib/voice-gateway/session-service.ts): `src/lib/voice-gateway/session-service.ts`

### Other components

- **Operator**
- **OpenShell**
- **Inference Providers**
- **Agent Runtime**
- **Messaging Channels**

## Connections

- Operator → NemoClaw CLI: invokes CLI
- NemoClaw CLI → Onboarding: dispatches
- Onboarding → Agent Definitions: selects agent
- Onboarding → Inference Routing: configures inference
- Onboarding → Sandbox Actions: starts sandbox
- Agent Definitions → Supported Agent Profiles: resolves profile
- Sandbox Actions → Blueprint Runner: runs blueprint
- Sandbox Actions → Container Engine: controls runtime
- Blueprint Runner → OpenShell: uses sandbox
- Rebuild Pipeline → Container Engine: recreates runtime
- Rebuild Pipeline → Snapshot Management: restores state
- Rebuild Pipeline → MCP Lifecycle Lock: coordinates lifecycle
- Snapshot Management → Runtime Authority: persists authority
- Network Policy → OpenShell: applies policy
- Container Engine → OpenShell: runs containers
- Inference Routing → Inference Providers: routes requests
- Inference Routing → Runtime Authority: verifies authority
- Model Storage Checks → Container Engine: probes storage
- Agent Runtime → Inference Routing: requests inference
- Agent Runtime → Messaging Rendering: renders channels
- Messaging Rendering → Messaging Channels: configures channels
- Messaging Build Plan → Agent Runtime: builds integration
- Voice Sessions → Agent Runtime: forwards turns
- Agent Runtime → Messaging Channels: exchanges messages
