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

```bash
# 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

```bash
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:
```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
```

### Step 3: Install OpenShell

```bash
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:
```bash
sudo usermod -aG docker $USER
newgrp docker
# or log out and back in
```

**cgroup v2 fix** — required for k3s inside Docker:
```bash
# 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

```bash
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:
```bash
fuser -k 8080/tcp
```

### Step 6: Verify

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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:**
```bash
cloudflared tunnel route dns <tunnel-name> nemoclaw.<domain>
```

**Update tunnel config** (`/etc/cloudflared/config.yml`):
```yaml
  - hostname: nemoclaw.<domain>
    service: http://localhost:18789
    originRequest:
      httpHostHeader: "127.0.0.1:18789"
```

**Restart tunnel:**
```bash
sudo systemctl restart cloudflared
```

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

```bash
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:

```bash
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:

```bash
# 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](https://github.com/NVIDIA/NemoClaw)
- [OpenShell GitHub](https://github.com/NVIDIA/OpenShell)
- [OpenClaw docs](https://docs.openclaw.ai)
- [NemoClaw quickstart](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart.html)
- [awesome-nemoclaw presets](https://github.com/VoltAgent/awesome-nemoclaw)
- [awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills)
- [device auth bug fix](https://github.com/openclaw/openclaw/issues/43909)