Skip to content

architecture.md

Latest commit

 

History

History
130 lines (103 loc) · 6.04 KB

architecture.md

File metadata and controls

130 lines (103 loc) · 6.04 KB
title
page nav
NemoClaw Architecture — Plugin, Blueprint, and Sandbox Structure
Architecture
description Plugin structure, blueprint lifecycle, sandbox environment, and inference routing.
keywords
nemoclaw architecture
nemoclaw plugin blueprint structure
topics
generative_ai
ai_agents
tags
openclaw
openshell
sandboxing
blueprints
inference_routing
content
type difficulty audience
reference
intermediate
developer
engineer
status published

Architecture

NemoClaw has two main components: a TypeScript plugin that integrates with the OpenClaw CLI, and a Python blueprint that orchestrates OpenShell resources.

NemoClaw Plugin

The plugin is a thin TypeScript package that registers an inference provider and the /nemoclaw slash command. It runs in-process with the OpenClaw gateway inside the sandbox.

nemoclaw/
├── src/
│   ├── index.ts                    Plugin entry — registers all commands
│   ├── cli.ts                      Commander.js subcommand wiring
│   ├── commands/
│   │   ├── launch.ts               Fresh install into OpenShell
│   │   ├── connect.ts              Interactive shell into sandbox
│   │   ├── status.ts               Blueprint run state + sandbox health
│   │   ├── logs.ts                 Stream blueprint and sandbox logs
│   │   └── slash.ts                /nemoclaw chat command handler
│   └── blueprint/
│       ├── resolve.ts              Version resolution, cache management
│       ├── fetch.ts                Download blueprint from OCI registry
│       ├── verify.ts               Digest verification, compatibility checks
│       ├── exec.ts                 Subprocess execution of blueprint runner
│       └── state.ts                Persistent state (run IDs)
├── openclaw.plugin.json            Plugin manifest
└── package.json                    Commands declared under openclaw.extensions

NemoClaw Blueprint

The blueprint is a versioned Python artifact with its own release stream. The plugin resolves, verifies, and executes the blueprint as a subprocess. The blueprint drives all interactions with the OpenShell CLI.

nemoclaw-blueprint/
├── blueprint.yaml                  Manifest — version, profiles, compatibility
├── orchestrator/
│   └── runner.py                   CLI runner — plan / apply / status
├── policies/
│   └── openclaw-sandbox.yaml       Default network + filesystem policy

Blueprint Lifecycle

flowchart LR
    A[resolve] --> B[verify digest]
    B --> C[plan]
    C --> D[apply]
    D --> E[status]
  1. Resolve. The plugin locates the blueprint artifact and checks the version against min_openshell_version and min_openclaw_version constraints in blueprint.yaml.
  2. Verify. The plugin checks the artifact digest against the expected value.
  3. Plan. The runner determines what OpenShell resources to create or update, such as the gateway, providers, sandbox, inference route, and policy.
  4. Apply. The runner executes the plan by calling openshell CLI commands.
  5. Status. The runner reports current state.

Sandbox Environment

The sandbox runs the ghcr.io/nvidia/openshell-community/sandboxes/openclaw container image. Inside the sandbox:

  • OpenClaw runs with the NemoClaw plugin pre-installed.
  • Inference calls are routed through OpenShell to the configured provider.
  • Network egress is restricted by the baseline policy in openclaw-sandbox.yaml.
  • Filesystem access is confined to /sandbox and /tmp for read-write access, with system paths read-only.

Inference Routing

Inference requests from the agent never leave the sandbox directly. OpenShell intercepts them and routes to the configured provider:

Agent (sandbox)  ──▶  OpenShell gateway  ──▶  NVIDIA Endpoint (build.nvidia.com)

Refer to Inference Profiles for provider configuration details.

Credential Handling

All user-provided secrets follow the same pattern:

  1. Stored on the host in ~/.nemoclaw/credentials.json (mode 0600) or as environment variables.
  2. Retrieved via getCredential(key) which checks env vars first, then the credentials file.
  3. Passed into the sandbox as environment variables at creation time.
  4. Never written to openclaw.json (immutable at runtime).

Credential Inventory

Credential Passed to sandbox Used inside sandbox Used on host Notes
NVIDIA_API_KEY Yes (env var) Yes — startup script writes auth-profiles.json Yes — deploy, Telegram bridge OpenClaw requires a specific JSON file format; nemoclaw-start.sh handles the translation
DISCORD_BOT_TOKEN Yes (env var) Yes — OpenClaw reads env var directly, auto-enables Discord channel No
SLACK_BOT_TOKEN Yes (env var) Yes — OpenClaw reads env var directly, auto-enables Slack channel No
TELEGRAM_BOT_TOKEN Yes (env var) Available but unused — bridge runs on host Yes — Telegram bridge (host-side) Bridge uses SSH to relay messages into sandbox
GITHUB_TOKEN Deploy path only No Yes — private repo access Not needed inside sandbox
Gateway auth token No — baked at build time Yes — openclaw.json (root:root 444) N/A Per-build unique, immutable security boundary

Why Telegram runs on the host

The Telegram bridge (scripts/telegram-bridge.js) runs on the host and communicates with the sandbox via OpenShell SSH. This is intentional:

  • It avoids giving the sandbox direct Telegram API access beyond what the network policy allows.
  • It allows the bridge to manage multiple sandboxes from one host process.
  • The TELEGRAM_BOT_TOKEN is still passed into the sandbox for future OpenClaw channel plugin support.