Lesson 2: Architecture Deep Dive

Understanding the five security layers, policy engine, and how components interact

NemoClaw implements a deny-by-default security model across five protection layers. Everything is blocked unless explicitly allowed.

The Five Protection Layers

NemoClaw's security isn't just "container isolation" - it's defense in depth across five distinct layers:

Five Protection Layers

flowchart TB subgraph LAYERS["NemoClaw Security Model"] direction TB L1["1. NETWORK
Deny-by-default egress
Binary-scoped rules
L4/L7 inspection
SSRF protection"] L2["2. FILESYSTEM
Read-only system paths
Landlock LSM enforcement
Writable: /sandbox, /tmp only"] L3["3. PROCESS
Capability drops (capsh)
no-new-privileges
512 process limit
Non-root user, PATH hardening"] L4["4. GATEWAY AUTH
Device authentication
Loopback binding (127.0.0.1)
Auto-pair allowlist
operator.admin requires manual approval"] L5["5. INFERENCE
All routes through inference.local
Credentials isolated on host
Injected at egress only"] end L1 --> L2 --> L3 --> L4 --> L5 style L1 fill:#e3f2fd,stroke:#1a5fb4,stroke-width:2px style L2 fill:#e8f5e9,stroke:#76b900,stroke-width:2px style L3 fill:#fff3e0,stroke:#f57c00,stroke-width:2px style L4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style L5 fill:#fce4ec,stroke:#c2185b,stroke-width:2px

Source: NVIDIA Security Best Practices

Layer 1: Network Security

Network Controls

Control What It Does
Deny-by-default egress All outbound connections blocked unless explicitly allowed
Binary-scoped rules Network policies can be tied to specific executables (e.g., only git can access github.com)
L4/L7 inspection Can inspect both transport (TCP/UDP) and application (HTTP) layers
SSRF protection Prevents server-side request forgery attacks

Network Policy Decision Flow

flowchart LR REQ["Outbound Request
from Agent"] PE["Policy Engine"] subgraph DECISIONS["Policy Decisions"] ALLOW["ALLOW
Destination + binary
match policy"] ROUTE["ROUTE
Strip caller creds
Inject backend creds
Forward to model"] DENY["DENY
Block request
Log it"] end REQ --> PE PE --> ALLOW PE --> ROUTE PE --> DENY style ALLOW fill:#e8f5e9,stroke:#76b900 style ROUTE fill:#e3f2fd,stroke:#1a5fb4 style DENY fill:#ffebee,stroke:#c62828

Source: NVIDIA Quickstart

Layer 2: Filesystem Security

Filesystem Controls (via Landlock LSM)

Path Permission Purpose
/usr, /lib, /proc, /etc Read-only System files - agent cannot modify
/sandbox Writable Agent workspace - project files go here
/tmp Writable Temporary files only

Enforcement: Landlock LSM at kernel level (Linux 5.13+) - cannot be bypassed from userspace.

"Enforced via Landlock LSM at kernel level on Linux 5.13+" — NVIDIA Sandbox Hardening

Layer 3: Process Security

Process Controls

Control Implementation
Capability drops Dangerous caps dropped via capsh (prevents privilege escalation)
no-new-privileges prctl flag - child processes cannot gain more privileges than parent
Process limit Maximum 512 processes in sandbox
File descriptor limit Maximum 65536 file descriptors
Non-root user Runs as 'sandbox' user, not root
PATH hardening PATH locked to prevent PATH injection attacks

Layer 4: Gateway Authentication

Gateway Controls

"operator.admin scope never auto-approved - requires explicit manual approval" — NVIDIA Security Docs

Layer 5: Inference Security

Inference Routing

Complete Data Flow Architecture

Here's how a request flows through the entire system:

Complete Request Flow

sequenceDiagram participant U as User participant NC as NemoClaw CLI participant BP as Blueprint participant GW as Gateway participant PE as Policy Engine participant SB as Sandbox participant AG as Agent (dcode) participant IL as inference.local participant PR as Privacy Router participant M as Model Provider Note over U,M: ONBOARDING PHASE U->>NC: nemoclaw onboard NC->>BP: Resolve blueprint BP->>BP: Verify SHA-256 digest NC->>GW: Create sandbox GW->>PE: Configure policies GW->>SB: Provision container GW->>AG: Install agent Note over U,M: EXECUTION PHASE U->>AG: Send task AG->>AG: Inspect → Edit → Run → Test AG->>IL: Request inference IL->>PE: Intercept on host PE->>PE: Validate request PE->>PR: Fetch credentials PR->>M: Forward with credentials M-->>PR: Response PR-->>AG: Return (creds stripped) AG-->>U: Summarize results

Policy Tiers

NemoClaw provides three preset security levels:

Tier Use Case Network Access Third-Party APIs
Restricted Maximum security, baseline only Minimal egress None
Balanced (default) Development workflows Dev tooling allowed Limited
Open Maximum flexibility Broad egress Broad access

What Lives Where

Inside vs Outside the Sandbox

flowchart TB subgraph OUTSIDE["OUTSIDE SANDBOX (Host)"] NC2["NemoClaw CLI"] GW2["OpenShell Gateway"] PE2["Policy Engine"] CREDS["API Keys & Credentials"] BPRES["Blueprint Resolution"] INJECT["Credential Injection"] end subgraph INSIDE["INSIDE SANDBOX (Container)"] AGENT["Agent Runtime (dcode/OpenClaw)"] TOOLS2["Tools: python, node, git, gh, vim"] MEM2["Agent Memory & State"] WRITE["Writable: /sandbox, /tmp"] READ["Read-only: /usr, /lib, /proc, /etc"] end OUTSIDE -->|"Policy enforced"| INSIDE INSIDE -->|"Requests to inference.local"| OUTSIDE style OUTSIDE fill:#e3f2fd,stroke:#1a5fb4,stroke-width:2px style INSIDE fill:#fff3e0,stroke:#f57c00,stroke-width:2px
The key insight: credentials and policy enforcement live on the host. The sandbox is a controlled environment where the agent can operate without access to sensitive resources.

Memory Secret Scanner

NemoClaw includes a plugin that scans agent memory writes for credential patterns:

Pattern Type Examples
API Keys OpenAI keys, Anthropic keys, NVIDIA API keys
Cloud Credentials AWS access keys, GCP service accounts
Authentication Tokens JWT tokens, OAuth tokens
Database Credentials Connection strings with passwords

The scanner covers 14 high-confidence patterns and blocks writes to persistent memory files containing these patterns.

How OpenShell Makes Agents Better for Domains

Your question: "How does OpenShell make the agent better for a given domain?"

1. Harness Tuning Without Weight Modification

Harness vs Model

flowchart LR subgraph AGENT["Agent System"] subgraph HARNESS["HARNESS (Scaffolding)"] SP["System Prompts"] TD["Tool Descriptions"] MW["Middleware"] end subgraph MODEL["MODEL (Thinking)"] W["Weights"] I["Inference"] end end HARNESS -->|"Can be tuned"| MODEL MODEL -->|"Returns thinking"| HARNESS style HARNESS fill:#e8f5e9,stroke:#76b900,stroke-width:2px style MODEL fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

"An agent has two components: the model (thinking) and the harness (scaffolding). The harness includes system prompts, tool descriptions, and middleware around model/tool calls." — LangChain Harness Tuning Blog

2. Context Engineering at Point of Need

Key finding from the Nemotron tuning playbook:

Guidance Location Effectiveness
System prompt: "When file read returns full page, assume there is more" Did nothing
Tool return: Same guidance injected when relevant Worked!

OpenShell's architecture supports injecting guidance contextually through the middleware layer rather than overloading system prompts.

3. Domain-Specific Benefits

Benefit How OpenShell Enables It
Reproducible environments Blueprints are versioned, digest-verified, immutable
Custom tooling Sandbox image includes domain-specific tools (COBOL, Maven, etc.)
Policy customization Network rules can be scoped to specific binaries and endpoints
Safe experimentation Isolated sandbox means agent mistakes don't affect host
Audit trails Logs + snapshots capture agent behavior for compliance

Knowledge Check

Primary Source Reading

Recommended Reading

NVIDIA Security Best Practices

https://docs.nvidia.com/nemoclaw/user-guide/openclaw/security/best-practices.md

This page details all five protection layers with implementation specifics.

Related Reference