> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/NemoClaw/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Plugin, blueprint, sandbox creation, and inference routing concepts for NemoClaw.

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.

<Note>
  NemoClaw is **alpha software**. Interfaces, APIs, and behavior may change without notice. See the [release notes](/about/release-notes) for current status.
</Note>

## 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.

| Component     | Role                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Plugin**    | TypeScript CLI commands for launch, connect, status, and logs. Registers under `nemoclaw` and `openclaw nemoclaw`. |
| **Blueprint** | Versioned Python artifact that orchestrates sandbox creation, policy application, and inference setup.             |
| **Sandbox**   | Isolated OpenShell container running OpenClaw with policy-enforced egress and filesystem.                          |
| **Inference** | NVIDIA 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:

```yaml theme={null}
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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

| Profile     | Provider     | Endpoint                              | Default model                       | Credential env   |
| ----------- | ------------ | ------------------------------------- | ----------------------------------- | ---------------- |
| `default`   | `nvidia-nim` | `https://integrate.api.nvidia.com/v1` | `nvidia/nemotron-3-super-120b-a12b` | `NVIDIA_API_KEY` |
| `ncp`       | `nvidia-ncp` | Configured at onboard time            | `nvidia/nemotron-3-super-120b-a12b` | `NVIDIA_API_KEY` |
| `nim-local` | `nim-local`  | `http://nim-service.local:8000/v1`    | `nvidia/nemotron-3-super-120b-a12b` | `NIM_API_KEY`    |
| `vllm`      | `vllm-local` | `http://localhost:8000/v1`            | `nvidia/nemotron-3-nano-30b-a3b`    | `OPENAI_API_KEY` |

<Note>
  The `nim-local` and `vllm` profiles are experimental. Use `default` or `ncp` for production.
</Note>

Get an API key from [build.nvidia.com](https://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.

| Layer          | What it protects                                     | When it applies             |
| -------------- | ---------------------------------------------------- | --------------------------- |
| **Network**    | Blocks unauthorized outbound connections.            | Hot-reloadable at runtime.  |
| **Filesystem** | Prevents reads/writes outside `/sandbox` and `/tmp`. | Locked at sandbox creation. |
| **Process**    | Blocks privilege escalation and dangerous syscalls.  | Locked at sandbox creation. |
| **Inference**  | Reroutes 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.

```console theme={null}
[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.

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Follow the step-by-step guide to install NemoClaw and run your first sandboxed agent.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/reference/architecture">
    Full technical reference: plugin file layout, blueprint lifecycle, and sandbox environment.
  </Card>

  <Card title="Inference profiles" icon="microchip" href="/reference/inference-profiles">
    Detailed provider configuration for NVIDIA Build, NCP, NIM, and local backends.
  </Card>

  <Card title="Network policies" icon="shield-halved" href="/reference/network-policies">
    Egress control, policy customization, and pre-approving trusted domains.
  </Card>
</CardGroup>