Intermediate

How It Works

Onboarding Flow

When you run nemoclaw onboard, the system executes a sequential creation process that provisions a fully secured agent environment. Click each step below to see details.

Sandbox Creation Pipeline

1
Plugin Initialization
Validates system environment (Node.js version, container runtime, disk space) and collects inference provider credentials interactively. Credentials stored on host only.
2
Blueprint Resolution
Checks latest blueprint version against constraints, downloads the artifact, and verifies its SHA-256 cryptographic digest to prevent supply-chain tampering.
3
Resource Planning
Evaluates CPU cores, RAM, and GPU availability to determine optimal configuration. GPU machines get local Nemotron inference; CPU-only defaults to cloud providers.
4
Sandbox Creation
Calls OpenShell CLI to create the isolated container. Landlock filesystem and seccomp process filters are applied and locked -- immutable after this point.
5
Policy Application
Network egress policies (from openclaw-sandbox.yaml) and inference routing policies are applied. These are hot-reloadable and adjustable at runtime.
6
Startup Verification
Runs health checks confirming sandbox is operational, inference provider is reachable, and all policy layers are active. Ready for connections.

Inference Routing

Every model API call from the agent is intercepted and routed through the privacy routerOpenShell component that routes inference requests to local or cloud models based on operator-defined policies, not agent preferences.. The agent never communicates directly with inference providers.

  1. Agent constructs an inference request (prompt + context) inside the sandbox
  2. NemoClaw plugin's registered inference provider intercepts the call
  3. Request is forwarded to the OpenShell gateway (outside the sandbox)
  4. Privacy router evaluates the request against configured policies
  5. Request routes to a local model (Nemotron via Ollama) or cloud endpoint (NVIDIA Endpoints, OpenAI, Anthropic, Gemini)
  6. Provider credentials are injected at the gateway -- the agent never sees API keys
  7. Response flows back through the gateway into the sandbox
💡
Key design decision: Routing logic lives outside the sandbox. The agent cannot influence which provider handles its requests. The default model is nvidia/nemotron-3-super-120b-a12b via NVIDIA Cloud API.

Network Policy Enforcement

NemoClaw uses a deny-by-default network model. All outbound connections are blocked unless explicitly allowed in the YAML policy file.

When the agent attempts to reach a blocked endpoint:

  1. OpenShell intercepts the connection at the network namespace boundary
  2. The connection is blocked and logged
  3. The blocked request surfaces in the operator's terminal UI (openshell term)
  4. The operator can approve the endpoint for the current session
  5. Session approvals persist until sandbox restart but do not modify baseline policy
📝
Practical tip: Over time, operators build up their allowlist by observing legitimate access patterns, creating a policy that matches actual usage without over-permitting.

Filesystem & Process Isolation

Filesystem (Landlock)

The sandbox filesystem access is enforced by the Landlock Linux Security Module:

Process (seccomp)

The seccomp filter profile drops dangerous system calls and prevents privilege escalation. The agent cannot use setuid/setgid, and operations like ptrace, mount, and reboot are blocked. The container runs as a non-root user with Docker capabilities dropped to the minimum set.

⚠️
Both are immutable: Filesystem and process restrictions are locked at sandbox creation. Even if the agent achieves code execution within the sandbox, Landlock prevents filesystem escalation at the kernel level.

State Management & Migration

NemoClaw supports migrating agent state between machines (e.g., moving from a dev laptop to a production GPU server). The migration process creates a snapshot, strips all credentials, exports as a portable artifact, then re-provisions on the target machine with local credentials. Credential stripping prevents accidental API key exposure when sharing states across environments.

📚 References & Resources