sarman/dgx-spark-playbooks
1
0
Fork 0
mirror of https://github.com/NVIDIA/dgx-spark-playbooks.git synced 2026-04-22 01:53:53 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

chore: Regenerate all playbooks

Browse Source
This commit is contained in:
GitLab CI 2026-03-16 22:31:40 +00:00
parent 76c2d7f17c
commit 54b01cf988
3 changed files with 941 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -37,12 +37,14 @@ Each playbook includes prerequisites, step-by-step instructions, troubleshooting
- [Connect Multiple Sparks through a Switch](nvidia/multi-sparks-through-switch/)
- [NCCL for Two Sparks](nvidia/nccl/)
- [Fine-tune with NeMo](nvidia/nemo-fine-tune/)
- [NemoClaw](nvidia/nemoclaw/)
- [Nemotron-3-Nano with llama.cpp](nvidia/nemotron/)
- [NIM on Spark](nvidia/nim-llm/)
- [NVFP4 Quantization](nvidia/nvfp4-quantization/)
- [Ollama](nvidia/ollama/)
- [Open WebUI with Ollama](nvidia/open-webui/)
- [OpenClaw 🦞](nvidia/openclaw/)
- [OpenClaw with OpenShell](nvidia/openshell/)
- [Portfolio Optimization](nvidia/portfolio-optimization/)
- [Fine-tune with Pytorch](nvidia/pytorch-fine-tune/)
- [RAG Application in AI Workbench](nvidia/rag-ai-workbench/)

493
nvidia/nemoclaw/README.md Normal file
View File

@ -0,0 +1,493 @@
# NemoClaw
> Run OpenClaw in an OpenShell sandbox on DGX Spark with Ollama (Nemotron)
## Table of Contents
- [Overview](#overview)
- [Quick start safety check](#quick-start-safety-check)
- [What you're getting](#what-youre-getting)
- [Key risks with AI agents](#key-risks-with-ai-agents)
- [Participant acknowledgement](#participant-acknowledgement)
- [Instructions](#instructions)
- [Troubleshooting](#troubleshooting)
---
## Overview
## Basic idea
**NVIDIA OpenShell** is an open-source runtime for running autonomous AI agents in sandboxed environments with kernel-level isolation. **NVIDIA NemoClaw** is an OpenClaw plugin that packages OpenShell with an AI agent: it includes the `nemoclaw onboard` wizard to automate setup so you can get a browser-based chat interface running locally on your DGX Spark using Ollama (e.g. NVIDIA Nemotron 3 Super).
By the end of this playbook you will have a working AI agent inside an OpenShell sandbox, accessible via a dashboard URL, with inference routed to a local model on your Spark—all without exposing your host filesystem or network to the agent.
## What you'll accomplish
- Install and configure Docker for OpenShell (including cgroup fix for DGX Spark)
- Install Node.js, Ollama, the OpenShell CLI, and the NemoClaw plugin
- Run the NemoClaw onboard wizard to create a sandbox and configure inference
- Start the OpenClaw web UI inside the sandbox and chat with Nemotron 3 Super (or another Ollama model) locally
## Notice and disclaimers
The following sections describe safety, risks, and your responsibilities when running this demo.
### Quick start safety check
**Use only a clean environment.** Run this demo on a fresh device or VM with no personal data, confidential information, or sensitive credentials. Keep it isolated like a sandbox.
By installing this demo, you accept responsibility for all third-party components, including reviewing their licenses, terms, and security posture. Read and accept before you install or use.
### What you're getting
This experience is provided "AS IS" for demonstration purposes only—no warranties, no guarantees. This is a demo, not a production-ready solution. You will need to implement appropriate security controls for your environment and use case.
### Key risks with AI agents
- **Data leakage** — Any materials the agent accesses could be exposed, leaked, or stolen.
- **Malicious code execution** — The agent or its connected tools could expose your system to malicious code or cyber-attacks.
- **Unintended actions** — The agent might modify or delete files, send messages, or access services without explicit approval.
- **Prompt injection and manipulation** — External inputs or connected content could hijack the agent's behavior in unexpected ways.
### Participant acknowledgement
By participating in this demo, you acknowledge that you are solely responsible for your configuration and for any data, accounts, and tools you connect. To the maximum extent permitted by law, NVIDIA is not responsible for any loss of data, device damage, security incidents, or other harm arising from your configuration or use of NemoClaw demo materials, including OpenClaw or any connected tools or services.
## Isolation layers (OpenShell)
| Layer | What it protects | When it applies |
|------------|----------------------------------------------------|-----------------------------|
| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. |
| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. |
| Process | Blocks privilege escalation and dangerous syscalls.| Locked at sandbox creation. |
| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. |
## What to know before starting
- Basic use of the Linux terminal and SSH
- Familiarity with Docker (permissions, `docker run`)
- Awareness of the security and risk sections above
## Prerequisites
**Hardware and access:**
- A DGX Spark (GB10) with keyboard and monitor, or SSH access
- An **NVIDIA API key** from [build.nvidia.com](https://build.nvidia.com) (free; the onboard wizard will prompt for it)
- A GitHub account with access to the NVIDIA organization (for installing the OpenShell CLI from GitHub releases)
**Software:**
- Fresh install of DGX OS with latest updates
Verify your system before starting:
```bash
head -n 2 /etc/os-release
nvidia-smi
docker info --format '{{.ServerVersion}}'
python3 --version
```
Expected: Ubuntu 24.04, NVIDIA GB10 GPU, Docker server version, Python 3.12+.
## Ancillary files
All required assets are in the [openshell-openclaw-plugin repository](https://github.com/NVIDIA/openshell-openclaw-plugin). You will clone it during the instructions to install NemoClaw.
## Time and risk
- **Estimated time:** 45–90 minutes (including first-time gateway and sandbox build, and Nemotron 3 Super download of ~87GB).
- **Risk level:** Medium — you are running an AI agent in a sandbox; risks are reduced by isolation but not eliminated. Use a clean environment and do not connect sensitive data or production accounts.
- **Rollback:** Remove the sandbox with `openshell sandbox delete <name>`, destroy the gateway with `openshell gateway destroy -g nemoclaw`, and uninstall NemoClaw with `sudo npm uninstall -g nemoclaw` and `rm -rf ~/.nemoclaw` (see Cleanup in Instructions).
- **Last Updated:** 03/13/2026
- First publication
## Instructions
## Step 1. Docker configuration
Verify Docker permissions and configure the NVIDIA runtime. OpenShell's gateway runs k3s inside Docker and on DGX Spark requires a cgroup setting so the gateway can start correctly.
Verify Docker:
```bash
docker ps
```
If you get a permission denied error, add your user to the Docker group:
```bash
sudo usermod -aG docker $USER
```
Log out and back in for the group to take effect.
Configure Docker for the NVIDIA runtime and set cgroup namespace mode for OpenShell on DGX Spark:
```bash
sudo nvidia-ctk runtime configure --runtime=docker
sudo python3 -c "
import json, os
path = '/etc/docker/daemon.json'
d = json.load(open(path)) if os.path.exists(path) else {}
d['default-cgroupns-mode'] = 'host'
json.dump(d, open(path, 'w'), indent=2)
"
sudo systemctl restart docker
```
Verify:
```bash
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
```
> [!NOTE]
> DGX Spark uses cgroup v2. OpenShell's gateway embeds k3s inside Docker and needs host cgroup namespace access. Without `default-cgroupns-mode: host`, the gateway can fail with "Failed to start ContainerManager" errors.
## Step 2. Install Node.js
NemoClaw is installed via npm and requires Node.js.
```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```
Verify: `node --version` should show v22.x.x.
## Step 3. Install Ollama and download a model
Install Ollama:
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
Verify it is running:
```bash
curl http://localhost:11434
```
Expected: `Ollama is running`. If not, start it: `ollama serve &`
Download Nemotron 3 Super 120B (~87GB; may take several minutes):
```bash
ollama pull nemotron-3-super:120b
```
Run it briefly to pre-load weights (type `/bye` to exit):
```bash
ollama run nemotron-3-super:120b
```
Configure Ollama to listen on all interfaces so the sandbox container can reach it:
```bash
sudo systemctl edit ollama.service
```
Add the following on the **third line** of the file (above "Edits below this comment will be discarded"):
```ini
[Service]
Environment="OLLAMA_HOST=0.0.0.0"
```
Save (Ctrl+X, then Y), then restart:
```bash
sudo systemctl daemon-reload
sudo systemctl restart ollama
```
## Step 4. Install the OpenShell CLI
The OpenShell binary is distributed via GitHub releases. You need the GitHub CLI and access to the NVIDIA organization.
```bash
sudo apt-get install -y gh
gh auth login
```
When using SSH, `gh` will show a one-time code. Visit https://github.com/login/device in a browser, enter the code, and authorize for the NVIDIA org.
Configure git for NVIDIA SAML SSO and download OpenShell:
```bash
gh auth setup-git
ARCH=$(uname -m)
case "$ARCH" in
x86_64|amd64) ARCH="x86_64" ;;
aarch64|arm64) ARCH="aarch64" ;;
esac
gh release download --repo NVIDIA/OpenShell \
--pattern "openshell-${ARCH}-unknown-linux-musl.tar.gz"
tar xzf openshell-${ARCH}-unknown-linux-musl.tar.gz
sudo install -m 755 openshell /usr/local/bin/openshell
rm -f openshell openshell-${ARCH}-unknown-linux-musl.tar.gz
```
Verify: `openshell --version`
## Step 5. Install NemoClaw
Clone the NemoClaw plugin and install it globally:
```bash
git clone https://github.com/NVIDIA/NemoClaw
cd NemoClaw
sudo npm install -g .
```
Verify: `nemoclaw --help`
> [!NOTE]
> OpenClaw (the AI agent) is installed **automatically inside the sandbox** during onboarding. You do not install it on the host.
## Step 6. Run the NemoClaw onboard wizard
Ensure Ollama is running (`curl http://localhost:11434` should return "Ollama is running"). From the directory where you cloned the plugin in Step 5 (e.g. `~/openshell-openclaw-plugin`), or that directory in a new terminal, run:
```bash
cd ~/openshell-openclaw-plugin
nemoclaw onboard
```
The wizard walks you through seven steps:
1. **NVIDIA API key** — Paste your key from [build.nvidia.com](https://build.nvidia.com) (starts with `nvapi-`). Only needed once.
2. **Preflight** — Checks Docker and OpenShell. "No GPU detected" is normal on DGX Spark (GB10 reports unified memory differently).
3. **Gateway** — Starts the OpenShell gateway (30–60 seconds on first run).
4. **Sandbox** — Enter a name or press Enter for the default. First build takes 2–5 minutes.
5. **Inference** — The wizard auto-detects Ollama (e.g. "Ollama detected on localhost:11434 — using it").
6. **OpenClaw** — Configured on first connect.
7. **Policies** — Press Enter or Y to accept suggested presets (pypi, npm).
When complete you will see something like:
```text
Dashboard http://localhost:18789/
Sandbox my-assistant (Landlock + seccomp + netns)
Model nemotron-3-nano (ollama-local)
```
## Step 7. Configure inference for Nemotron 3 Super
The onboard wizard defaults to `nemotron-3-nano`. Switch the inference route to the Super model you downloaded in Step 3:
```bash
openshell inference set --provider ollama-local --model nemotron-3-super:120b
```
Verify:
```bash
openshell inference get
```
Expected: `provider: ollama-local` and `model: nemotron-3-super:120b`.
## Step 8. Start the OpenClaw web UI
Connect to the sandbox (use the name you chose in Step 6, e.g. `my-assistant`):
```bash
openshell sandbox connect my-assistant
```
You are now inside the sandbox. Run these commands in order.
Set the API key environment variables (required for the gateway). For local Ollama, use the value `local-ollama` — no real API key is required. If you use a different inference provider later, replace with your API key:
```bash
export NVIDIA_API_KEY=local-ollama
export ANTHROPIC_API_KEY=local-ollama
```
Initialize NemoClaw (this may drop you into a new shell when done):
```bash
nemoclaw-start
```
After the "NemoClaw ready" banner, re-export the environment variables:
```bash
export NVIDIA_API_KEY=local-ollama
export ANTHROPIC_API_KEY=local-ollama
```
Create memory files and start the web UI:
```bash
mkdir -p /sandbox/.openclaw/workspace/memory
echo "# Memory" > /sandbox/.openclaw/workspace/MEMORY.md
openclaw config set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback true
nohup openclaw gateway run \
--allow-unconfigured --dev \
--bind loopback --port 18789 \
> /tmp/gateway.log 2>&1 &
```
Wait a few seconds, then get your dashboard URL:
```bash
openclaw dashboard
```
This prints something like:
```text
Dashboard URL: http://127.0.0.1:18789/#token=YOUR_UNIQUE_TOKEN
```
**Save this URL.** Type `exit` to leave the sandbox (the gateway keeps running).
## Step 9. Open the chat interface
Open the dashboard URL from Step 8 in your Spark's web browser:
```text
http://127.0.0.1:18789/#token=YOUR_UNIQUE_TOKEN
```
> [!IMPORTANT]
> The token is in the URL as a hash fragment (`#token=...`), not a query parameter (`?token=`). Paste the full URL including `#token=...` into the address bar.
You should see the OpenClaw dashboard with **Version** and **Health: OK**. Click **Chat** in the left sidebar and send a message to your agent.
Try: *"Hello! What can you help me with?"* or *"How many rs are there in the word strawberry?"*
> [!NOTE]
> Nemotron 3 Super 120B responses may take 30–90 seconds. This is normal for a 120B parameter model running locally.
## Step 10. Using the agent from the command line
Connect to the sandbox:
```bash
openshell sandbox connect my-assistant
```
Run a prompt:
```bash
export NVIDIA_API_KEY=local-ollama
export ANTHROPIC_API_KEY=local-ollama
openclaw agent --agent main --local -m "How many rs are there in strawberry?" --session-id s1
```
Test sandbox isolation (this should be blocked by the network policy):
```bash
curl -sI https://httpbin.org/get
```
Type `exit` to leave the sandbox.
## Step 11. Monitoring with the OpenShell TUI
In a separate terminal on the host:
```bash
openshell term
```
Press `f` to follow live output, `s` to filter by source, `q` to quit.
## Step 12. Cleanup
Remove the sandbox and destroy the NemoClaw gateway:
```bash
openshell sandbox delete my-assistant
openshell gateway destroy -g nemoclaw
```
To fully uninstall NemoClaw:
```bash
sudo npm uninstall -g nemoclaw
rm -rf ~/.nemoclaw
```
## Step 13. Clean slate (start over)
To remove everything and start again from Step 5:
```bash
cd ~
openshell sandbox delete my-assistant 2>/dev/null
openshell gateway destroy -g nemoclaw 2>/dev/null
sudo npm uninstall -g nemoclaw
rm -rf ~/openshell-openclaw-plugin ~/.nemoclaw
```
Verify:
```bash
which nemoclaw # Should report "not found"
openshell status # Should report "No gateway configured"
```
Then restart from Step 5 (Install NemoClaw).
## Step 14. Optional: Remote access via SSH
If you access the Spark remotely, forward port 18789 to your machine.
**SSH tunnel** (from your local machine, not the Spark):
```bash
ssh -L 18789:127.0.0.1:18789 your-user@your-spark-ip
```
Then open the dashboard URL in your local browser.
**Cursor / VS Code:** Open the **Ports** tab in the bottom panel, click **Forward a Port**, enter **18789**, then open the dashboard URL in your browser.
## Useful commands
| Command | Description |
|---------|-------------|
| `openshell status` | Check gateway health |
| `openshell sandbox list` | List all running sandboxes |
| `openshell sandbox connect my-assistant` | Shell into the sandbox |
| `openshell term` | Open the monitoring TUI |
| `openshell inference get` | Show current inference routing |
| `openshell forward list` | List active port forwards |
| `nemoclaw my-assistant connect` | Connect to sandbox (alternate) |
| `nemoclaw my-assistant status` | Show sandbox status |
## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| Gateway fails with cgroup / "Failed to start ContainerManager" errors | Docker not configured for host cgroup namespace on DGX Spark | Run the cgroup fix: `sudo python3 -c "import json, os; path='/etc/docker/daemon.json'; d=json.load(open(path)) if os.path.exists(path) else {}; d['default-cgroupns-mode']='host'; json.dump(d, open(path,'w'), indent=2)"` then `sudo systemctl restart docker` |
| "No GPU detected" during onboard | DGX Spark GB10 reports unified memory differently | Expected on DGX Spark. The wizard still works and will use Ollama for inference. |
| "unauthorized: gateway token missing" | Dashboard URL used without token or wrong format | Paste the **full URL** including `#token=...` (hash fragment, not `?token=`). Run `openclaw dashboard` inside the sandbox to get the URL again. |
| "No API key found for provider anthropic" | API key env vars not set when starting gateway in sandbox | Inside the sandbox, set both before running the gateway: `export NVIDIA_API_KEY=local-ollama` and `export ANTHROPIC_API_KEY=local-ollama` |
| Agent gives no response | Model not loaded or Nemotron 3 Super is slow | Nemotron 3 Super can take 30–90 seconds per response. Verify Ollama: `curl http://localhost:11434`. Ensure inference is set: `openshell inference get` |
| Port forward dies or dashboard unreachable | Forward not active or wrong port | List forwards: `openshell forward list`. Restart: `openshell forward stop 18789 my-assistant` then `openshell forward start --background 18789 my-assistant` |
| Docker permission denied | User not in docker group | `sudo usermod -aG docker $USER`, then log out and back in. |
| Ollama not reachable from sandbox (503 / timeout) | Ollama bound to localhost only or firewall blocking 11434 | Ensure Ollama listens on all interfaces: add `Environment="OLLAMA_HOST=0.0.0.0"` in `sudo systemctl edit ollama.service`, then `sudo systemctl daemon-reload` and `sudo systemctl restart ollama`. If using UFW: `sudo ufw allow 11434/tcp comment 'Ollama for NemoClaw'` and `sudo ufw reload` |
> [!NOTE]
> DGX Spark uses a Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU. With many applications still updating to take advantage of UMA, you may encounter memory issues even when within the memory capacity of DGX Spark. If that happens, manually flush the buffer cache with:
```bash
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
```
For the latest known issues, please review the [DGX Spark User Guide](https://docs.nvidia.com/dgx/dgx-spark/known-issues.html).

446
nvidia/openshell/README.md Normal file
View File

@ -0,0 +1,446 @@
# OpenClaw with OpenShell
> Run OpenClaw in an NVIDIA OpenShell sandbox on DGX Spark
## Table of Contents
- [Overview](#overview)
- [Notice & Disclaimers](#notice-disclaimers)
- [Instructions](#instructions)
- [Troubleshooting](#troubleshooting)
---
## Overview
## Basic idea
OpenClaw is a local-first AI agent that runs on your machine, combining memory, file access, tool use, and community skills into a persistent assistant. Running it directly on your system means the agent can access your files, credentials, and network—creating real security risks.
**NVIDIA OpenShell** solves this problem. It is an open-source sandbox runtime that wraps the agent in kernel-level isolation with declarative YAML policies. OpenShell controls what the agent can read on disk, which network endpoints it can reach, and what privileges it has—without disabling the capabilities that make the agent useful.
By combining OpenClaw with OpenShell on DGX Spark, you get the full power of a local AI agent backed by 128GB of unified memory for large models, while enforcing explicit controls over filesystem access, network egress, and credential handling.
### Notice & Disclaimers
#### Quick Start Safety Check
Use a clean environment only. Run this playbook on a fresh device or VM with no personal data, confidential information, or sensitive credentials. Think of it like a sandbox—keep it isolated.
By installing this playbook, you're taking responsibility for all third-party components, including reviewing their licenses, terms, and security posture. Read and accept before you install or use.
---
#### What You're Getting
The playbook showcases experimental AI agent capabilities. Even with cutting-edge open-source tools like OpenShell in your toolkit, you need to layer in proper security measures for your specific threat model.
---
#### Key Risks with AI Agents
Be mindful of these risks with AI agents:
1. Data leakage – Any materials the agent accesses could be exposed, leaked, or stolen.
2. Malicious code execution – The agent or its connected tools could expose your system to malicious code or cyber-attacks.
3. Unintended actions – The agent might modify or delete files, send messages, or access services without explicit approval.
4. Prompt injection & manipulation – External inputs or connected content could hijack the agent's behavior in unexpected ways.
---
#### Security Best Practices
No system is perfect, but these practices help keep your information and systems safe.
1. Isolate your environment – Run on a clean PC or isolated virtual machine. Only provision the specific data you want the agent to access.
2. Never use real accounts – Don't connect personal, confidential, or production accounts. Create dedicated test accounts with minimal permissions.
3. Vet your skills/plugins – Only enable skills from trusted sources that have been vetted by the community.
4. Lock down access – Ensure your OpenClaw UI or messaging channels aren't accessible over the network without proper authentication.
5. Restrict network access – Where feasible, limit the agent's internet connectivity.
6. Clean up after yourself – When you're done, remove OpenClaw and revoke all credentials, API keys, and account access you granted.
---
## What you'll accomplish
You will install the OpenShell CLI (`openshell`), deploy a gateway on your DGX Spark, and launch OpenClaw inside a sandboxed environment using the pre-built OpenClaw community sandbox. The sandbox enforces filesystem, network, and process isolation by default. You will also configure local inference routing so OpenClaw uses a model running on your Spark without needing external API keys.
## Popular use cases
- **Secure agent experimentation**: Test OpenClaw skills and integrations without exposing your main filesystem or credentials to the agent.
- **Private enterprise development**: Route all inference to a local model on DGX Spark. No data leaves the machine unless you explicitly allow it in the policy.
- **Auditable agent access**: Version-control the policy YAML alongside your project. Review exactly what the agent can reach before granting access.
- **Iterative policy tuning**: Monitor denied connections in real time with `openshell term`, then hot-reload updated policies without recreating the sandbox.
## What to know before starting
- Comfort with the Linux terminal and SSH
- Basic understanding of Docker (OpenShell runs a k3s cluster inside Docker)
- Familiarity with Ollama for local model serving
- Awareness of the security model: OpenShell reduces risk through isolation but cannot eliminate all risk. Review the [OpenShell documentation](https://pypi.org/project/openshell/) and [OpenClaw security guidance](https://docs.openclaw.ai/gateway/security).
## Prerequisites
**Hardware Requirements:**
- NVIDIA DGX Spark with 128GB unified memory
- At least 70GB available memory for a large local model (e.g., gpt-oss:120b at ~65GB plus overhead), or 25GB+ for a smaller model (e.g., gpt-oss-20b)
**Software Requirements:**
- NVIDIA DGX OS (Ubuntu 24.04 base)
- Docker Desktop or Docker Engine running: `docker info`
- Python 3.12 or later: `python3 --version`
- `uv` package manager: `uv --version` (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- Ollama 0.17.0 or newer (latest recommended for gpt-oss MXFP4 support): `ollama --version`
- Network access to download Python packages from PyPI and model weights from Ollama
- Have [NVIDIA Sync](https://build.nvidia.com/spark/connect-to-your-spark) installed and configured for your DGX Spark
## Time & risk
* **Estimated time:** 20–30 minutes (plus model download time, which depends on model size and network speed).
> [!CAUTION] **Risk level:** Medium
* OpenShell sandboxes enforce kernel-level isolation, significantly reducing the risk compared to running OpenClaw directly on the host.
* The sandbox default policy denies all outbound traffic not explicitly allowed. Misconfigured policies may block legitimate agent traffic; use `openshell logs` to diagnose.
* Large model downloads may fail on unstable networks.
* **Rollback:** Delete the sandbox with `openshell sandbox delete <sandbox-name>`, stop the gateway with `openshell gateway stop`, and optionally destroy it with `openshell gateway destroy`. Ollama models can be removed with `ollama rm <model>`.
* **Last Updated:** 03/13/2026
## Instructions
## Step 1. Confirm your environment
Verify the OS, GPU, Docker, and Python are available before installing anything.
```bash
head -n 2 /etc/os-release
nvidia-smi
docker info --format '{{.ServerVersion}}'
python3 --version
```
Ensure [NVIDIA Sync](https://build.nvidia.com/spark/connect-to-your-spark/sync) is configured with a custom port: use "OpenClaw" as the Name and "18789" as the port.
Expected output should show Ubuntu 24.04 (DGX OS), a detected GPU, a Docker server version, and Python 3.12+.
## Step 2. Docker Configuration
First, verify that the local user has Docker permissions using the following command.
``` bash
docker ps
```
If you get a permission denied error (`permission denied while trying to connect to the docker API at unix:///var/run/docker.sock`), add your user to the system's Docker group. This will enable you to run Docker commands without requiring `sudo`. The command to do so is as follows:
``` bash
sudo usermod -aG docker $USER
newgrp docker
```
Note that you should reboot the Spark after adding the user to the group for this to take persistent effect across all terminal sessions.
Now that we have verified the user's Docker permission, we must configure Docker so that it can use the NVIDIA Container Runtime.
``` bash
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
## Run a sample workload to verify the setup
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
```
## Step 3. Install the OpenShell CLI
Create a virtual environment and install the `openshell` CLI.
```bash
cd ~
uv venv openshell-env && source openshell-env/bin/activate
uv pip install openshell
openshell --help
```
If you don't have `uv` installed yet:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
```
Expected output should show the `openshell` command tree with subcommands like `gateway`, `sandbox`, `provider`, and `inference`.
## Step 4. Deploy the OpenShell gateway on DGX Spark
The gateway is the control plane that manages sandboxes. Since you are running directly on the Spark, it deploys locally inside Docker.
```bash
openshell gateway start
openshell status
```
`openshell status` should report the gateway as **healthy**. The first run may take a minute while Docker pulls the required images.
> [!NOTE]
> Remote gateway deployment requires passwordless SSH access. Ensure your SSH public key is added to `~/.ssh/authorized_keys` on the DGX Spark before using the `--remote` flag.
> [!TIP]
> If you want to manage the Spark gateway from a separate workstation, run `openshell gateway start --remote <username>@<spark-ssid>.local` from that workstation instead. All subsequent commands will route through the SSH tunnel.
## Step 5. Install Ollama and pull a model
Install Ollama (if not already present) and download a model for local inference.
```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama --version
```
DGX Spark's 128GB memory can run large models:
| GPU memory available | Suggested model | Model size | Notes |
|---------------------|-------------------------|-----------|-------|
| 25–48 GB | gpt-oss:20b | ~12GB | Lower latency, good for interactive use |
| 48–80 GB | Nemotron-3-Nano-30B-A3B | ~20GB | Good balance of quality and speed |
| 128 GB | gpt-oss:120b | ~65GB | Best quality on DGX Spark |
Verify Ollama is running (it auto-starts as a service after installation). If not, start it manually:
```bash
ollama serve &
```
Next, run a model from Ollama (adjust the model name to match your choice from [the Ollama model library](https://ollama.com/library)). The `ollama run` command will pull the model automatically if it is not already present. Running the model here ensures it is loaded and ready when you use it with OpenClaw, reducing the chance of timeouts later. Example for GPT-OSS 120b:
```bash
ollama run gpt-oss:120b
```
Verify the model is available:
```bash
ollama list
```
## Step 6. Create an inference provider
We are going to create an OpenShell provider that points to your local Ollama server. This lets OpenShell route inference requests to your Spark-hosted model. To create a provider for the cluster, please replace `{Machine_IP}` with the IP Address of your DGX Spark.
```bash
openshell provider create \
--name local-ollama \
--type openai \
--credential OPENAI_API_KEY=not-needed \
--config OPENAI_BASE_URL=http://{Machine_IP}:11434/v1
```
> [!NOTE]
> `host.docker.internal` resolves to the host machine from inside Docker containers. If your Ollama listens on a different port or host, adjust the URL accordingly.
## Step 7. Configure inference routing
Point the `inference.local` endpoint (available inside every sandbox) at your Ollama model:
```bash
openshell inference set \
--provider local-ollama \
--model gpt-oss:120b
```
Verify the configuration:
```bash
openshell inference get
```
Expected output should show `provider: local-ollama` and `model: gpt-oss:120b` (or whichever model you chose).
## Step 8. Deploy OpenShell Sandbox
Create a sandbox using the pre-built OpenClaw community sandbox. This pulls the OpenClaw Dockerfile, the default policy, and startup scripts from the OpenShell Community catalog:
``` bash
openshell sandbox create \
--keep \
--forward 18789 \
--name dgx-demo \
--from openclaw \
-- openclaw-start
```
> [!NOTE]
> Do not pass `--policy` with a local file path (e.g. `openclaw-policy.yaml`) when using `--from openclaw`. The policy is bundled with the community sandbox; a local file path can cause "file not found."
The `--keep` flag keeps the sandbox running after the initial process exits, so you can reconnect later. This is the default behavior. To terminate the sandbox when the initial process exits, use the `--no-keep` flag instead.
> [!NOTE]
> The sandbox name is displayed in the creation output. You can also set it explicitly with `--name <your-name>`. To find it later, run `openshell sandbox list`.
The CLI will:
1. Resolve `openclaw` against the community catalog
2. Pull and build the container image
3. Apply the bundled sandbox policy
4. Launch OpenClaw inside the sandbox
In order to verify the default policy enabled for your sandbox, please run the following command:
```bash
openshell sandbox get <sandbox_name>
```
## Step 9. Configure OpenClaw within OpenShell Sandbox
The sandbox container will spin up and you will be guided through the OpenClaw installation process. Work through the prompts as follows.
Use the arrow keys and Enter key to interact with the installation.
- If you understand and agree, use the arrow key of your keyboard to select 'Yes' and press the Enter key.
- Quickstart vs Manual: select Quickstart and press the Enter key.
- Model/auth Provider: Select **Custom Provider**, the second-to-last option.
- API Base URL: update to https://inference.local/v1
- How do you want to provide this API key?: Paste API key for now.
- API key: please enter "ollama".
- Endpoint compatibility: select **OpenAI-compatible** and press Enter.
- Model ID: gpt-oss:120b
- This may take 1-2 minutes as the Ollama model is spun up in the background.
- Endpoint ID: leave the default value.
- Alias: gpt-oss:120b (this is optional).
- Channel: Select **Skip for now**.
- Skills: Select **No** for now.
- Enable hooks: Select **No** for now and press Enter.
It might take 1-2 minutes to get through the final stages. Afterwards, you should see a URL with a token you can use to connect to the gateway.
The expected output will be similar, but the token will be unique.
``` bash
OpenClaw gateway starting in background.
Logs: /tmp/gateway.log
UI: http://127.0.0.1:18789/?token=9b4c9a9c9f6905131327ce55b6d044bd53e0ec423dd6189e
```
If you are using the Spark as the primary device, right-click on the URL in the UI section and select Open Link.
**Accessing the dashboard from the host or a remote system:** The dashboard URL (e.g. `http://127.0.0.1:18789/?token=...`) is inside the sandbox, so the host does not forward port 18789 by default. To reach it from your host or another machine, use SSH local port forwarding. From a machine that can reach the OpenShell gateway, run (replace gateway URL, sandbox-id, token, and gateway-name with values from your environment):
```bash
ssh -o ProxyCommand='/usr/local/bin/openshell ssh-proxy --gateway https://127.0.0.1:8080/connect/ssh --sandbox-id <sandbox-id> --token <token> --gateway-name openshell' -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -N -L 18789:127.0.0.1:18789 sandbox
```
Then open `http://127.0.0.1:18789/?token=<your-token>` in your local browser.
Otherwise, if you are using NVIDIA Sync, right-click on the URL listed in the UI and select Copy Link. Next, connect to your Spark and select the OpenClaw entry. When your web browser opens the tab for OpenClaw, paste the URL in the navigation bar and press the Enter key.
From this page, you can now **Chat** with your OpenClaw agent within the protected confines of the runtime OpenShell provides.
## Step 10. Conduct Inference within Sandbox
#### Connecting to the Sandbox (Terminal)
Now that OpenClaw has been configured within the OpenShell protected runtime, you can connect directly into the sandbox environment via:
```bash
openshell sandbox connect dgx-demo
```
Once loaded into the sandbox terminal, you can test connectivity to the Ollama model with this command:
``` bash
curl https://inference.local/v1/responses \
-H "Content-Type: application/json" \
-d '{
"instructions": "You are a helpful assistant.",
"input": "Hello!"
}'
```
## Step 11. Verify sandbox isolation
Open a second terminal and check the sandbox status and live logs:
```bash
source ~/openshell-env/bin/activate
openshell term
```
The terminal dashboard shows:
- **Sandbox status** — name, phase, image, providers, and port forwards
- **Live log stream** — outbound connections, policy decisions (`allow`, `deny`, `inspect_for_inference`), and inference interceptions
Verify that the OpenClaw agent can reach `inference.local` for model requests and that unauthorized outbound traffic is denied.
> [!TIP]
> Press `f` to follow live output, `s` to filter by source, and `q` to quit the terminal dashboard.
## Step 12. Reconnect to the sandbox
If you exit the sandbox session, reconnect at any time:
```bash
openshell sandbox connect
```
To transfer files in or out (replace `<sandbox-name>` with your sandbox name from the creation output or from `openshell sandbox list`):
```bash
openshell sandbox upload <sandbox-name> ./local-file /sandbox/destination
openshell sandbox download <sandbox-name> /sandbox/file ./local-destination
```
## Step 13. Cleanup
Stop and remove the sandbox:
```bash
openshell sandbox delete <sandbox-name>
```
Stop the gateway (preserves state for later):
```bash
openshell gateway stop
```
> [!WARNING]
> The following command permanently removes the gateway cluster and all its data.
```bash
openshell gateway destroy
```
To also remove the Ollama model:
```bash
ollama rm gpt-oss:120b
```
## Step 14. Next steps
- **Add more providers**: Attach GitHub tokens, GitLab tokens, or cloud API keys as providers with `openshell provider create`. When creating the sandbox, pass the provider name(s) with `--provider <name>` (e.g. `--provider my-github`) to inject those credentials into the sandbox securely.
- **Try other community sandboxes**: Run `openshell sandbox create --from base` or `--from sdg` for other pre-built environments.
- **Connect VS Code**: Use `openshell sandbox ssh-config <sandbox-name>` and append the output to `~/.ssh/config` to connect VS Code Remote-SSH directly into the sandbox.
- **Monitor and audit**: Use `openshell logs <sandbox-name> --tail` or `openshell term` to continuously monitor agent activity and policy decisions.
## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| `openshell gateway start` fails with "connection refused" or Docker errors | Docker is not running | Start Docker with `sudo systemctl start docker` or launch Docker Desktop, then retry `openshell gateway start` |
| `openshell status` shows gateway as unhealthy | Gateway container crashed or failed to initialize | Run `openshell gateway destroy` and then `openshell gateway start` to recreate it. Check Docker logs with `docker ps -a` and `docker logs <container-id>` for details |
| `openshell sandbox create --from openclaw` fails to build | Network issue pulling the community sandbox or Dockerfile build failure | Check internet connectivity. Retry the command. If the build fails on a specific package, check if the base image is compatible with your Docker version |
| Sandbox is in `Error` phase after creation | Policy validation failed or container startup crashed | Run `openshell logs <sandbox-name>` to see error details. Common causes: invalid policy YAML, missing provider credentials, or port conflicts |
| Agent cannot reach `inference.local` inside the sandbox | Inference routing not configured or provider unreachable | Run `openshell inference get` to verify the provider and model are set. Test Ollama is accessible from the host: `curl http://localhost:11434/api/tags`. Ensure the provider URL uses `host.docker.internal` instead of `localhost` |
| 503 verification failed or timeout when gateway/sandbox accesses Ollama on the host | Ollama bound only to localhost, or host firewall blocking port 11434 | Make Ollama listen on all interfaces so the gateway container (e.g. on Docker network 172.17.x.x) can reach it: `OLLAMA_HOST=0.0.0.0 ollama serve &`. Allow port 11434 through the host firewall: `sudo ufw allow 11434/tcp comment 'Ollama for OpenShell Gateway'` (then `sudo ufw reload` if needed). |
| Agent's outbound connections are all denied | Default policy does not include the required endpoints | Monitor denials with `openshell logs <sandbox-name> --tail --source sandbox`. Pull the current policy with `openshell policy get <sandbox-name> --full`, add the needed host/port under `network_policies`, and push with `openshell policy set <sandbox-name> --policy <file> --wait` |
| "Permission denied" or Landlock errors inside the sandbox | Agent trying to access a path not in `read_only` or `read_write` filesystem policy | Pull the current policy and add the path to `read_write` (or `read_only` if read access is sufficient). Push the updated policy. Note: filesystem policy is static and requires sandbox recreation |
| Ollama OOM or very slow inference | Model too large for available memory or GPU contention | Free GPU memory (close other GPU workloads), try a smaller model (e.g., `gpt-oss:20b`), or reduce context length. Monitor with `nvidia-smi` |
| `openshell sandbox connect` hangs or times out | Sandbox not in `Ready` phase | Run `openshell sandbox get <sandbox-name>` to check the phase. If stuck in `Provisioning`, wait or check logs. If in `Error`, delete and recreate the sandbox |
| Policy push returns exit code 1 (validation failed) | Malformed YAML or invalid policy fields | Check the YAML syntax. Common issues: paths not starting with `/`, `..` traversal in paths, `root` as `run_as_user`, or endpoints missing required `host`/`port` fields. Fix and re-push |
| `openshell gateway start` fails with "K8s namespace not ready" / timed out waiting for namespace | The k3s cluster inside the Docker container takes longer to bootstrap than the CLI timeout allows. The internal components (TLS secrets, Helm chart, namespace creation) may need extra time, especially on first run when images are pulled inside the container. | First, check whether the container is still running and progressing: `docker ps --filter name=openshell` (look for `health: starting`). Inspect k3s state inside the container: `docker exec <container> sh -c "KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get ns"` and `kubectl get pods -A`. If pods are in `ContainerCreating` and TLS secrets are missing (`navigator-server-tls`, `openshell-server-tls`), the cluster is still bootstrapping — wait a few minutes and run `openshell status` again. If it does not recover, destroy with `openshell gateway destroy` (and `docker rm -f <container>` if needed) and retry `openshell gateway start`. Ensure Docker has enough resources (memory and disk) for the k3s cluster. |
| `openshell status` says "No gateway configured" even though the Docker container is running | The `gateway start` command failed or timed out before it could save the gateway configuration to the local config store | The container may still be healthy — check with `docker ps --filter name=openshell`. If the container is running and healthy, try `openshell gateway start` again (it should detect the existing container). If the container is unhealthy or stuck, remove it with `docker rm -f <container>` and then `openshell gateway destroy` followed by `openshell gateway start`. |
> [!NOTE]
> DGX Spark uses a Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU.
> With many applications still updating to take advantage of UMA, you may encounter memory issues even when within
> the memory capacity of DGX Spark. If that happens, manually flush the buffer cache with:
```bash
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
```
For the latest known issues, please review the [DGX Spark User Guide](https://docs.nvidia.com/dgx/dgx-spark/known-issues.html).