Lesson 7: Blueprint to OpenShell Flow

This lesson provides a comprehensive deep dive into the journey from a Blueprint YAML file to a fully running, secured AI agent. We'll explore the onboarding process, SHA-256 verification, resource creation, and agent startup sequence.

1. Blueprint Structure

1.1 What is a Blueprint?

A Blueprint is a versioned YAML package that defines everything needed to create and run a sandboxed AI agent. It bundles the sandbox image specification, security policies, inference configuration, and supporting assets into a single, immutable artifact.

The key principle behind blueprints is supply chain safety: all artifacts are immutable, versioned, and digest-verified before execution. This ensures reproducible deployments and prevents tampering.

1.2 Complete YAML Schema

The blueprint YAML follows a structured schema with these key sections:

# Blueprint YAML Schema (Annotated)
apiVersion: nemoclaw/v1
kind: Blueprint
metadata:
  name: my-agent-blueprint           # Unique identifier
  version: 1.2.0                     # Semantic version
  description: "Production agent"    # Human-readable description
  digest: sha256:abc123...           # Cryptographic hash of contents

spec:
  # Agent selection - which agent framework to use
  agent:
    type: openclaw                   # openclaw | hermes | langchain-deepagents-code
    version: "2.1.0"                 # Agent framework version

  # Container image specification
  sandbox:
    image: ghcr.io/nvidia/nemoclaw-sandbox:latest
    pullPolicy: IfNotPresent
    resources:
      limits:
        memory: "8Gi"
        cpu: "4"
      requests:
        memory: "4Gi"
        cpu: "2"

  # Inference provider configuration
  inference:
    provider: build                  # build | openrouter | openai | anthropic | etc.
    model: nemotron-4-340b-instruct  # Model identifier
    endpoint: inference.local        # Routed through gateway
    parameters:
      temperature: 0.7
      max_tokens: 4096

  # Network security policy
  network:
    tier: balanced                   # balanced | restricted | open
    endpoints:
      - host: "api.github.com"
        port: 443
        protocol: rest
        methods: [GET, POST]
        paths: ["/repos/**", "/users/**"]
      - host: "*.pypi.org"
        port: 443
        protocol: none              # L4 only - no inspection

  # Filesystem layout (locked at creation)
  filesystem:
    writable:
      - /sandbox                     # Agent working directory
      - /tmp                         # Temporary files
    readonly:
      - /usr                         # System binaries
      - /lib                         # Shared libraries
      - /app                         # Application code

  # Process security (locked at creation)
  process:
    user: sandbox
    capabilities_drop:
      - cap_sys_admin
      - cap_sys_ptrace
      - cap_net_raw

  # Web search configuration (optional)
  webSearch:
    provider: brave                  # brave | tavily | none

  # Messaging channels (optional)
  messaging:
    channels:
      - type: slack
        allowedUsers: ["U12345"]
      - type: telegram
        allowedIds: ["123456789"]

1.3 Blueprint Field Reference

1.4 Example Blueprints Comparison

Different agent frameworks have different default configurations:

Source: NemoClaw How It Works Documentation

2. The Onboarding Flow

2.1 What Happens When You Run nemoclaw onboard

The nemoclaw onboard command initiates a multi-step orchestration process that transforms a blueprint into a running, secured agent environment. This process involves resolution, verification, resource creation, and startup.

2.2 Step-by-Step CLI Commands

The onboarding wizard guides you through each step:

2.3 Detailed Onboarding Process Flow

The complete onboarding process consists of 13 discrete steps:

Step 1:  Preflight checks (Docker, platform, GPU, memory, disk)
           |
Step 2:  Start/reuse OpenShell gateway
           |
Step 3:  Select inference provider and model
           |
Step 4:  Collect credentials (via secure helper)
           |
Step 5:  Enter sandbox name
           |
Step 6:  Review configuration summary
           |
Step 7:  Register provider with OpenShell
           |
Step 8:  Prompt for web search (Brave/Tavily)
           |
Step 9:  Prompt for messaging channels (Telegram/Discord/Slack)
           |
Step 10: Build sandbox image (5-15 minutes typical)
           |
Step 11: Apply network policy tier (Balanced/Restricted/Open)
           |
Step 12: Verify readiness (gateway, dashboard, inference.local route)
           |
Step 13: Display ready summary with dashboard URL

2.4 Non-Interactive Onboarding

For CI/CD pipelines or automated deployments, use environment variables:

# Non-interactive onboarding example
curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
  NEMOCLAW_NON_INTERACTIVE=1 \
  NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
  NEMOCLAW_AGENT=openclaw \
  NEMOCLAW_PROVIDER=build \
  NVIDIA_INFERENCE_API_KEY=nvapi-xxxxx \
  NEMOCLAW_SANDBOX_NAME=my-agent \
  bash

Source: NemoClaw Quickstart Guide

3. SHA-256 Verification

3.1 How Digest Verification Works

Every blueprint includes a SHA-256 cryptographic hash that ensures integrity. Before any resources are created, NemoClaw verifies that the blueprint contents match the expected digest.

3.2 Why Immutability Matters

Blueprint immutability provides critical security guarantees:

• Reproducibility - Running setup again recreates the exact same sandbox from the same blueprint and policy definitions
• Supply Chain Security - Prevents man-in-the-middle attacks where blueprints could be modified in transit
• Auditability - The digest serves as a permanent record of exactly what was deployed
• Rollback Confidence - You can always return to a known-good configuration

# Blueprint manifest with digest
metadata:
  name: production-agent
  version: 2.1.0
  digest: sha256:1a42bbe8dbc9003cb79d4e641b53760571aacd85293671aee97c09c0746fef33

3.3 What Happens If Verification Fails

When digest verification fails, NemoClaw takes these protective actions:

1. Immediate Halt - No resources are created or modified
2. Error Report - Clear message indicating tampering detected
3. Audit Log - Failed verification attempt is logged
4. No Fallback - Unlike some systems, there is no "proceed anyway" option

# Example verification failure
$ nemoclaw onboard --blueprint compromised-agent

ERROR: Blueprint verification failed
  Expected digest: sha256:1a42bbe8dbc9003cb79d4...
  Computed digest: sha256:9f8e7d6c5b4a3219087f...

The blueprint has been modified since it was signed.
This could indicate:
  - Corruption during download
  - Unauthorized modification
  - Man-in-the-middle attack

No resources have been created. Please verify the blueprint source.

3.4 Secure Credential Helper Verification

Even the credential helper scripts are digest-verified:

Helper: scripts/local-credential-helper.mts
  SHA-256: 1a42bbe8dbc9003cb79d4e641b53760571aacd85293671aee97c09c0746fef33

Form: docs/resources/local-credential-form.html
  SHA-256: 5512a256e0ad7c63a26ab82cf4f5924e98652097172ab8a5dc9d9358dd4f6ae8

Source: NemoClaw How It Works Documentation

4. Resource Creation

After blueprint verification passes, the runner determines which OpenShell resources to create or update. This involves four key components: Gateway, Provider, Sandbox, and Policy.

4.1 Gateway Setup

The OpenShell Gateway is the central orchestration component that owns sandbox lifecycle, networking, policy enforcement, and inference routing.

Gateway Responsibilities:

• Sandbox creation, destruction, and health monitoring
• All egress traffic interception and inspection
• Policy rule evaluation and enforcement
• Inference request routing via inference.local
• Credential injection for managed providers

# Gateway is started/reused during onboarding
# Check gateway status
openshell gateway status

# Gateway serves all sandboxes on the host
openshell gateway list-sandboxes

4.2 Provider Configuration

During onboarding, NemoClaw validates and registers the selected inference provider:

The provider configuration process:

1. Validate credentials via test API call
2. Register provider route with OpenShell gateway
3. Bake matching model reference into sandbox image
4. Configure inference.local routing

4.3 Sandbox Provisioning

The sandbox image is built with all security configurations baked in:

# Sandbox build process (5-15 minutes typical)
# 1. Pull base image
# 2. Install agent framework
# 3. Configure inference endpoint
# 4. Apply filesystem layout
# 5. Set process constraints
# 6. Remove dangerous tools (gcc, make, netcat)
# 7. Lock PATH

# Resulting sandbox has:
#   - Writable: /sandbox, /tmp
#   - Read-only: /usr, /lib, /app, /etc
#   - Landlock LSM enforcement
#   - Dropped capabilities
#   - Seccomp-BPF filtering

Filesystem protections are locked at sandbox creation and cannot be modified at runtime:

• System paths (/usr, /lib, /etc) restricted to read-only
• Only /sandbox and /tmp are writable
• Compiler toolchains removed from runtime image

4.4 Policy Activation

Network policies are applied during onboarding but can be modified at runtime:

# Three network policy tiers available
Balanced   - Common dev presets (npm, PyPI, Hugging Face, Homebrew) + web search
Restricted - Minimal network access
Open       - Broader access (not recommended for production)

Policy configuration is hot-reloadable:

# View current policy
openshell policy get my-sandbox

# Update policy at runtime
openshell policy set my-sandbox --tier restricted

# Add specific endpoint
openshell policy add my-sandbox --host api.example.com --port 443

Source: NemoClaw Quickstart Guide

5. Agent Startup

5.1 How the Agent is Installed

The agent framework is installed into the sandbox image during the build phase. The specific installation depends on the agent type:

5.2 Initial Configuration

When the sandbox container starts, the following initialization sequence occurs:

5.3 First Run Behavior

On first run, the NemoClaw plugin performs these registration steps:

1. Managed Provider Metadata - Registers available inference providers and models
2. Slash Command Registration - Enables /nemoclaw commands in the agent
3. Runtime Context Hooks - Injects system guidance as context
4. Gateway Communication - Establishes connection via inference.local

# After startup, verify agent is ready
nemoclaw my-sandbox status

# Expected output:
Sandbox: my-sandbox
Status: Ready
Model: claude-sonnet-4-20250514
Provider: anthropic-managed
Gateway: Connected
Dashboard: http://127.0.0.1:18789/sandbox/my-sandbox

# Connect to agent terminal
nemoclaw my-sandbox connect

5.4 Protection Layers Applied at Startup

5.5 Inference Routing via inference.local

All agent requests to LLM providers are routed through the gateway's inference.local endpoint:

# Inside sandbox, agent makes request to:
https://inference.local/v1/chat/completions

# Gateway intercepts and:
# 1. Validates request against inference policy
# 2. Injects managed credentials
# 3. Routes to actual provider (Anthropic, OpenAI, etc.)
# 4. Returns response to agent

This provides:

• Credential isolation - Agent never sees actual API keys
• Model enforcement - Can restrict to specific models
• Usage tracking - All inference calls are logged
• Provider switching - Change providers without agent modification

Source: NemoClaw How It Works Documentation

6. Complete Flow Diagram

Here's the end-to-end journey from blueprint to running agent:

7. Environment Variables Reference

Key environment variables for configuring the onboarding process:

Quiz: Test Your Understanding

References

• NemoClaw How It Works Documentation - Blueprint structure and verification flow
• NemoClaw Quickstart Guide - CLI commands and onboarding process
• NVIDIA OpenShell GitHub Repository - Source code and technical details
• OpenClaw Security Documentation - Security architecture and protections
• OpenClaw Sandbox Management - Runtime management commands