Skip to main content
NemoClaw combines a lightweight CLI plugin with a versioned blueprint to move OpenClaw into a controlled OpenShell sandbox. This page explains the key concepts at a high level.
NemoClaw is alpha software. Interfaces, APIs, and behavior may change without notice. See the release notes for current status.

​
How the pieces fit together

The nemoclaw CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents. It delegates the heavy lifting to a versioned blueprint — a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI.
ComponentRole
PluginTypeScript CLI commands for launch, connect, status, and logs. Registers under nemoclaw and openclaw nemoclaw.
BlueprintVersioned Python artifact that orchestrates sandbox creation, policy application, and inference setup.
SandboxIsolated OpenShell container running OpenClaw with policy-enforced egress and filesystem.
InferenceNVIDIA cloud model calls, routed through the OpenShell gateway, transparent to the agent.
The flow from a user command to a running sandbox looks like this: 
nemoclaw onboard
    └── nemoclaw plugin
            └── blueprint runner
                    └── openshell CLI
                            ├── sandbox
                            ├── gateway
                            ├── inference provider
                            └── network policy
                                    └── OpenShell Sandbox
                                            ├── OpenClaw agent
                                            ├── NVIDIA inference (routed)
                                            ├── strict network policy
                                            └── filesystem isolation

​
Design principles

NemoClaw’s architecture is built around five principles: Thin plugin, versioned blueprint The plugin stays small and stable. Orchestration logic lives in the blueprint, which evolves on its own release cadence. Updating the blueprint does not require updating the plugin. Respect CLI boundaries The nemoclaw host CLI is the primary interface. Plugin commands are also available under openclaw nemoclaw, but they do not override built-in OpenClaw commands. Supply chain safety Blueprint artifacts are immutable, versioned, and digest-verified before execution. The blueprint manifest includes a digest field computed at release time. The plugin verifies this digest before running any blueprint code. OpenShell-native for new installs For users without an existing OpenClaw installation, NemoClaw recommends openshell sandbox create directly rather than a plugin-driven bootstrap. This avoids installing OpenClaw on the host only to redeploy it inside OpenShell. Reproducible setup Running setup again recreates the sandbox from the same blueprint and policy definitions. The sandbox image (ghcr.io/nvidia/openshell-community/sandboxes/openclaw:latest) is pinned per blueprint version.

​
Plugin and blueprint

NemoClaw is split into two distinct parts:
  • The plugin is a TypeScript package that powers the nemoclaw host CLI and also registers commands under openclaw nemoclaw. It handles user interaction, validates inputs, and delegates orchestration work to the blueprint.
  • The blueprint is a versioned Python artifact (defined in blueprint.yaml) that contains all the logic for creating sandboxes, applying policies, and configuring inference providers. The plugin resolves, verifies, and executes the blueprint as a subprocess.
This separation keeps the plugin small and stable while allowing the blueprint to evolve independently. The blueprint manifest specifies minimum version requirements for both OpenShell and OpenClaw: 
version: "0.1.0"
min_openshell_version: "0.1.0"
min_openclaw_version: "2026.3.0"
The blueprint defines four profiles — default, ncp, nim-local, and vllm — each corresponding to a different inference backend.

​
Sandbox creation flow

When you run nemoclaw onboard, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. The blueprint orchestrates this process through the OpenShell CLI.
1

Resolve and verify the blueprint

The plugin downloads the blueprint artifact and checks version compatibility against the installed versions of OpenShell and OpenClaw. It then verifies the artifact’s SHA digest against the value recorded in the manifest. If verification fails, execution stops.
2

Plan the deployment

The blueprint runs in plan mode to determine which OpenShell resources need to be created or updated — the gateway, inference providers, sandbox container, and network policy.
3

Apply through the OpenShell CLI

The blueprint calls OpenShell CLI commands to create the sandbox and configure each resource. For the default profile, this includes:
  • Creating the OpenClaw sandbox container from ghcr.io/nvidia/openshell-community/sandboxes/openclaw:latest
  • Registering the inference provider (nvidia-inference) pointing to https://integrate.api.nvidia.com/v1
  • Applying the baseline network and filesystem policy from sandboxes/openclaw/policy.yaml
  • Forwarding port 18789 for the OpenClaw API
4

Sandbox starts with policies enforced

After the sandbox starts, the agent runs inside it with all network, filesystem, and inference controls active. Policy is enforced from the first instruction the agent executes.
5

State is saved

The plugin records the blueprint run ID, blueprint version, and sandbox name in its local state. This enables nemoclaw status and nemoclaw logs to reference the correct run.

​
Inference routing

Inference requests from the agent never leave the sandbox directly. OpenShell intercepts every inference call at the gateway and routes it to the configured provider. 
OpenClaw agent
    └── (inference call)
            └── OpenShell gateway
                    └── NVIDIA cloud (build.nvidia.com)
                            └── Nemotron model
NemoClaw routes inference to NVIDIA cloud by default. You can switch models at runtime without restarting the sandbox.
ProfileProviderEndpointDefault modelCredential env
defaultnvidia-nimhttps://integrate.api.nvidia.com/v1nvidia/nemotron-3-super-120b-a12bNVIDIA_API_KEY
ncpnvidia-ncpConfigured at onboard timenvidia/nemotron-3-super-120b-a12bNVIDIA_API_KEY
nim-localnim-localhttp://nim-service.local:8000/v1nvidia/nemotron-3-super-120b-a12bNIM_API_KEY
vllmvllm-localhttp://localhost:8000/v1nvidia/nemotron-3-nano-30b-a3bOPENAI_API_KEY
The nim-local and vllm profiles are experimental. Use default or ncp for production.
Get an API key from build.nvidia.com. The nemoclaw onboard command prompts for this key during setup.

​
Network and filesystem policy

The sandbox starts with a strict baseline policy defined in sandboxes/openclaw/policy.yaml. This policy controls which network endpoints the agent can reach and which filesystem paths it can access.
LayerWhat it protectsWhen it applies
NetworkBlocks unauthorized outbound connections.Hot-reloadable at runtime.
FilesystemPrevents reads/writes outside /sandbox and /tmp.Locked at sandbox creation.
ProcessBlocks privilege escalation and dangerous syscalls.Locked at sandbox creation.
InferenceReroutes model API calls to controlled backends.Hot-reloadable at runtime.

​
Network policy

Only endpoints listed in the policy are allowed. When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. 
[OpenShell TUI] Blocked: agent → api.example.com:443
Allow this connection? [y/N]
Approved endpoints persist for the current session but are not saved to the baseline policy file. To permanently allow a domain, add it to the policy and re-apply.

​
Filesystem policy

The agent can write to /sandbox and /tmp. All other system paths are read-only. This is enforced using Landlock LSM and cannot be changed at runtime.

​
Process isolation

The sandbox uses seccomp to block privilege escalation syscalls and a dedicated network namespace to prevent direct host network access. These controls are applied at sandbox creation and cannot be hot-reloaded.

​
Diagnosing issues

Errors may originate from either NemoClaw or the OpenShell layer underneath. 
# Check NemoClaw-level sandbox health
nemoclaw my-assistant status

# Check the underlying OpenShell sandbox state
openshell sandbox list

# Stream blueprint execution and sandbox logs
nemoclaw my-assistant logs --follow

​
Next steps

Quickstart

Follow the step-by-step guide to install NemoClaw and run your first sandboxed agent.

Architecture

Full technical reference: plugin file layout, blueprint lifecycle, and sandbox environment.

Inference profiles

Detailed provider configuration for NVIDIA Build, NCP, NIM, and local backends.

Network policies

Egress control, policy customization, and pre-approving trusted domains.

Build docs developers (and LLMs) love

Get started for freeTalk to us