setting-up-nemoclaw-environment

name	setting-up-nemoclaw-environment
description	Guides NemoClaw installation, onboarding, and initial configuration including OpenShell gateway, sandbox creation, and NVIDIA inference setup. Use when setting up NemoClaw for the first time, reconfiguring, or troubleshooting setup issues.

Setting Up NemoClaw Environment

NemoClaw requires a working host environment before sandboxes can be created. All setup commands run on the host — the user's machine where Claude Code operates — unless otherwise noted.

Preflight Checklist

Before running setup, verify the host meets all requirements by running the bundled preflight script:

bash scripts/preflight_check.sh

The script checks OS compatibility, Docker availability, Node.js/npm versions, available disk space, and RAM. It prints PASS/FAIL for each requirement and exits non-zero if any critical check fails.

System Requirements

Requirement	Minimum
OS	Ubuntu 22.04 LTS+ (macOS supported via Docker Desktop)
Node.js	20+
npm	10+
Container runtime	Docker Engine, Docker Desktop, or Colima
CPU	4 vCPU
RAM	8 GB
Disk	20 GB free

Installation

Install the NemoClaw CLI:

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

After installation, run nemoclaw --help to verify it's on your PATH.

Setup Paths

NemoClaw provides multiple entry points for initial configuration.

Interactive Onboard Wizard

nemoclaw onboard

The wizard walks through each configuration step with prompts and explanations: configuring inference endpoint and credentials, setting up the OpenShell gateway, and creating the initial sandbox. This is the recommended path for most users.

DGX Spark Setup

nemoclaw setup-spark

DGX Spark specific setup that fixes cgroup v2 and Docker configuration issues. Use this on NVIDIA DGX Spark hardware before or after nemoclaw onboard.

NVIDIA API Key Configuration

NemoClaw uses the NVIDIA API for cloud inference. A valid API key is required when using the nvidia-nim provider.

• Obtain a key from build.nvidia.com.
• During nemoclaw onboard, the key is prompted and saved to ~/.nemoclaw/credentials.json.
• To update the key manually, edit ~/.nemoclaw/credentials.json or re-run nemoclaw onboard.
• The key is injected into sandboxes automatically via OpenShell provider configuration.

Inference Providers

NemoClaw supports multiple inference backends. Switch between them at runtime:

# Switch to NVIDIA Cloud
openshell inference set --provider nvidia-nim --model nvidia/nemotron-3-super-120b-a12b

# Switch to Local vLLM
openshell inference set --provider vllm-local --model nvidia/nemotron-3-nano-30b-a3b

# Switch to Local NIM
openshell inference set --provider nim-local --model nvidia/nemotron-3-super-120b-a12b

# Check current inference config
openshell inference get

Verification

After setup completes, verify the environment end-to-end.

Step 1 — Check sandbox status (HOST-side)

nemoclaw status
openshell sandbox list
openshell inference get

Step 2 — Connect to the sandbox (HOST-side)

nemoclaw <name> connect

Step 3 — Test inference (SANDBOX-side)

Once inside the container, run:

openclaw agent --agent main --local -m "Test inference" --session-id debug

A successful response from the agent confirms that the OpenShell gateway, inference provider, and sandbox are all configured correctly.

Troubleshooting

For common setup failures and their fixes, see reference/troubleshooting.md.