nemoclaw-setup

name	nemoclaw-setup
description	Install and configure NVIDIA NemoClaw (sandboxed OpenClaw agent platform) on Linux. Handles cloudflared tunnels, Docker cgroup fixes, OpenShell, sandbox creation, remote access via Cloudflare Tunnel, and known bug workarounds. Use whenever the user mentions installing NemoClaw, setting up OpenClaw, configuring an NVIDIA Spark or DGX for sandboxed agents, or troubleshooting NemoClaw deployment.
compatibility	claude-code-only

NemoClaw Setup

Install NVIDIA NemoClaw — a sandboxed AI agent platform built on OpenClaw with Landlock + seccomp + network namespace isolation. Runs inside Docker via k3s (OpenShell).

What You Get

• Sandboxed AI agent with web UI and terminal CLI
• Powered by NVIDIA Nemotron models (cloud or local)
• Network-policy-controlled access to external services
• Optional remote access via Cloudflare Tunnel

Prerequisites

Requirement	Check	Install
Linux (Ubuntu 22.04+)	uname -a	—
Docker	docker ps	sudo apt install docker.io
Node.js 20+ (22 recommended)	node --version	nvm install 22
NVIDIA GPU (optional but recommended)	nvidia-smi	—
NVIDIA API key	—	https://build.nvidia.com/settings/api-keys

Workflow

Step 1: Pre-flight Checks

# Check Docker
docker ps 2>/dev/null || echo "Docker not running or no access"

# Check Node.js
node --version

# Check if already installed
which nemoclaw && nemoclaw --version
which openshell && openshell --version

If nemoclaw is already installed, skip to Step 4.

Step 2: Install NemoClaw

curl -fsSL https://nvidia.com/nemoclaw.sh | bash

This installs NemoClaw and OpenClaw via npm globally (to ~/.npm-global/bin/).

If the installer can't find Node.js, install it first:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Step 3: Install OpenShell

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

Installs to ~/.local/bin/openshell.

Step 4: Fix Docker Permissions and cgroup

Docker group — the user must be in the docker group:

sudo usermod -aG docker $USER
newgrp docker
# or log out and back in

cgroup v2 fix — required for k3s inside Docker:

# Check if needed
grep cgroup2 /proc/filesystems && echo "cgroup v2 detected — fix needed"

# Apply fix (needs sudo)
sudo $HOME/.npm-global/bin/nemoclaw setup-spark

This adds "default-cgroupns-mode": "host" to /etc/docker/daemon.json and restarts Docker.

IMPORTANT: The nemoclaw setup-spark command also asks for an NVIDIA API key. Have it ready (starts with nvapi-). Get one at https://build.nvidia.com/settings/api-keys.

Step 5: Run Onboarding

PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw onboard

The interactive wizard will:

1. Check Docker and OpenShell
2. Start the OpenShell gateway (k3s in Docker)
3. Ask for a sandbox name — use claw or any name
4. Configure the NVIDIA API key
5. Set up inference (Nemotron 3 Super 120B via cloud API)
6. Launch OpenClaw inside the sandbox
7. Apply network policy presets — select the ones you need

Common port conflict: If port 8080 is in use, find and kill the process:

fuser -k 8080/tcp

Step 6: Verify

# Check sandbox is running
PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw status

# Connect via terminal
PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw connect

Step 7: Set Up Web UI Access

The web UI runs inside the sandbox and needs a port forward:

PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH openshell forward start 18789 claw

Then open: http://127.0.0.1:18789/

Known bug (OpenClaw ≤ v2026.3.11): "device identity required" error. Workaround — append the gateway token to the URL:

# Get the token
ssh -F /tmp/nemoclaw-ssh-config openshell-claw \
  "python3 -c \"import json; print(json.load(open('/sandbox/.openclaw/openclaw.json'))['gateway']['auth']['token'])\""

Then visit: http://127.0.0.1:18789/#token=<gateway-token>

Fix: Update to OpenClaw v2026.3.12+ (see Updating section below).

Step 8: Make the Port Forward Persistent

Create a health-checked keepalive script:

cat > ~/.local/bin/nemoclaw-keepalive.sh << 'KEEPALIVE'
#!/bin/bash
export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
cleanup() { kill %1 2>/dev/null; exit 0; }
trap cleanup SIGTERM SIGINT
while true; do
    fuser -k 18789/tcp 2>/dev/null; sleep 1
    openshell forward start 18789 claw &
    FORWARD_PID=$!; sleep 3
    while kill -0 $FORWARD_PID 2>/dev/null; do
        if ! curl -sf -o /dev/null --connect-timeout 3 http://127.0.0.1:18789/ 2>/dev/null; then
            echo "$(date): Health check failed, restarting..."
            kill $FORWARD_PID 2>/dev/null; wait $FORWARD_PID 2>/dev/null; break
        fi
        sleep 10
    done
    echo "$(date): Forward died, restarting in 3s..."; sleep 3
done
KEEPALIVE
chmod +x ~/.local/bin/nemoclaw-keepalive.sh

Create the systemd service:

sudo tee /etc/systemd/system/nemoclaw-forward.service << 'SERVICE'
[Unit]
Description=NemoClaw Port Forward with Health Check
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=$USER
Group=docker
Environment=PATH=/home/$USER/.npm-global/bin:/home/$USER/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/$USER/.local/bin/nemoclaw-keepalive.sh
Restart=always
RestartSec=5
KillMode=control-group

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl daemon-reload
sudo systemctl enable nemoclaw-forward
sudo systemctl start nemoclaw-forward

Step 9: Remote Access via Cloudflare Tunnel (Optional)

If you have a Cloudflare Tunnel already running, add NemoClaw to it.

Add DNS route:

cloudflared tunnel route dns <tunnel-name> nemoclaw.<domain>

Update tunnel config (/etc/cloudflared/config.yml):

  - hostname: nemoclaw.<domain>
    service: http://localhost:18789
    originRequest:
      httpHostHeader: "127.0.0.1:18789"

Restart tunnel:

sudo systemctl restart cloudflared

Update sandbox allowed origins — SSH into the sandbox and add your domain:

openshell sandbox ssh-config claw > /tmp/nemoclaw-ssh-config

ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'python3 -c "
import json
with open(\"/sandbox/.openclaw/openclaw.json\") as f:
    config = json.load(f)
config[\"gateway\"][\"controlUi\"][\"allowedOrigins\"].append(\"https://nemoclaw.<domain>\")
config[\"gateway\"][\"trustedProxies\"] = [\"127.0.0.1\", \"::1\", \"172.0.0.0/8\", \"10.0.0.0/8\"]
config[\"gateway\"][\"allowRealIpFallback\"] = True
with open(\"/sandbox/.openclaw/openclaw.json\", \"w\") as f:
    json.dump(config, f, indent=2)
print(\"Done. Token:\", config[\"gateway\"][\"auth\"][\"token\"])
"'

Protect with Cloudflare Access — add the hostname to your Access application in the Zero Trust dashboard.

Access URL: https://nemoclaw.<domain>/#token=<gateway-token>

Step 10: Install Custom Skills

Skills are markdown files in /sandbox/.openclaw/skills/<name>/SKILL.md. SSH into the sandbox to create them:

ssh -F /tmp/nemoclaw-ssh-config openshell-claw
mkdir -p /sandbox/.openclaw/skills/my-skill
cat > /sandbox/.openclaw/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill does.
tools: [exec, read, write]
---
# My Skill
Instructions for the agent...
EOF

Verify with: openclaw skills list

Step 11: Configure the Workspace

Update the workspace files so the agent knows who you are:

• /sandbox/.openclaw/workspace/USER.md — your profile, preferences
• /sandbox/.openclaw/workspace/TOOLS.md — available tools and access
• /sandbox/.openclaw/workspace/SOUL.md — agent personality and behaviour

Updating OpenClaw

The sandbox bundles OpenClaw at install time. To update:

# 1. Update host-side packages
npm install -g openclaw@latest

# 2. Destroy and recreate sandbox
nemoclaw claw destroy
nemoclaw onboard

# 3. Reconfigure remote access (Step 9) and skills (Step 10)

Note: Sandbox network policies block npm/PyPI inside the sandbox. Updates must be done by rebuilding.

Troubleshooting

Issue	Cause	Fix
Docker is not running	Docker service stopped or user not in docker group	sudo systemctl start docker then newgrp docker
cgroup v2 detected	Docker not configured for cgroupns=host	sudo nemoclaw setup-spark
Port 8080 in use	Another service on that port	fuser -k 8080/tcp
nemoclaw: command not found	Not in PATH	PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH
device identity required	Bug in OpenClaw ≤ v2026.3.11	Append #token=<gateway-token> to URL, or update to v2026.3.12+
gateway token mismatch	Token changed after sandbox rebuild	Get new token from sandbox config
too many failed auth attempts	Rate limited from old token attempts	Restart gateway: ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'pkill -f "openclaw gateway"; sleep 2; openclaw gateway &'
origin not allowed	Domain not in allowedOrigins	Add to gateway.controlUi.allowedOrigins in sandbox config
Port 18789 not responding	SSH tunnel died	sudo systemctl restart nemoclaw-forward (auto-recovers within 13s)
npm 403 Forbidden inside sandbox	Network policy blocking TLS	Cannot install packages inside sandbox — rebuild instead
Tunnel not found on DNS route	Wrong Cloudflare account/cert	Check cloudflared tunnel list matches your cert
Error 502 on Cloudflare	Tunnel connections dropped	sudo systemctl restart cloudflared
Assets 404 via Cloudflare	Browser not authenticated for sub-requests	Hard refresh (Ctrl+Shift+R) after Cloudflare Access login

Architecture

Docker (openshell-cluster-<name>)
  └─ k3s cluster
      ├─ NVIDIA device plugin
      └─ OpenShell sandbox
          ├─ OpenClaw agent
          ├─ NemoClaw plugin
          ├─ Gateway (WebSocket + REST)
          └─ Workspace (SOUL.md, USER.md, TOOLS.md, skills/)

Port forward (systemd): localhost:18789 ←SSH tunnel→ sandbox:18789
Cloudflare Tunnel (optional): nemoclaw.domain → localhost:18789

References

• NemoClaw GitHub
• OpenShell GitHub
• OpenClaw docs
• NemoClaw quickstart
• awesome-nemoclaw presets
• awesome-openclaw-skills
• device auth bug fix