NemoClaw Cookbook

Thin deployment and integration helpers for upstream NemoClaw and OpenShell.

This is a community cookbook / reference implementation, not an official NVIDIA project. For NemoClaw or OpenShell issues, file upstream issues in those repositories.

Upstream-First

This repo is not a fork and not a competing distribution. It exists to make NemoClaw easier to deploy while upstream support is still landing. Every patch should be temporary: when upstream absorbs a capability, this cookbook deletes its version.

The current upstream alignment notes are in UPSTREAM.md.

Secret Hygiene

Tokenized dashboard URLs, gateway tokens, API keys, and bot tokens are live credentials. The cookbook treats them as non-printable runtime values: scripts write them to files, pass them directly to browsers or clients, and redact them in status output. Do not paste tokenized URLs into issues, PRs, chat, shell transcripts, or shared logs.

Prerequisites

• A Brev Ubuntu instance with Docker
• Brev CLI installed and authenticated locally
• An NVIDIA API key from https://build.nvidia.com/

Setup

Create a local .env, copy it to the Brev instance, then run the cookbook setup script on the instance:

cp .env.example .env
# Edit .env. NVIDIA_API_KEY is required.

brev exec <instance> "git clone -b main https://github.com/stevenrick/nemoclaw-cookbook.git ~/nemoclaw-cookbook"
brev copy .env <instance>:~/.env
brev exec <instance> "cd ~/nemoclaw-cookbook && ./setup.sh"

Connect after setup:

# Secure Link, if TUNNEL_FQDN is set. Opens without printing the tokenized URL.
URL=$(brev exec <instance> "sed -n '1p' ~/openclaw-tunnel-url.txt" | sed -n '/^https:/p' | head -1)
open "$URL"

# Browser terminal on the same Secure Link.
TERMINAL_URL=$(printf '%s' "$URL" | sed 's#/#/terminal#3')
open "$TERMINAL_URL"

# Port-forward fallback
brev port-forward <instance> -p 18789:18789
URL=$(brev exec <instance> "sed -n '1p' ~/openclaw-ui-url.txt" | sed -n '/^http:/p' | head -1)
open "$URL"

See BUILD.md for the full setup walkthrough and USE.md for day-to-day commands.

What This Sets Up

• Upstream NemoClaw and OpenShell, using NemoClaw's own scripts/install-openshell.sh
• An OpenClaw assistant inside an OpenShell sandbox
• nginx reverse proxy for the dashboard, Secure Link origin handling, and optional /v1/* CORS
• Optional browser terminal at /terminal for OpenShell policy approvals
• Optional upstream messaging channels for Telegram, Discord, Slack, WeChat, and WhatsApp
• Upstream sandbox resource profiles via NEMOCLAW_RESOURCE_PROFILE, NEMOCLAW_CPU, and NEMOCLAW_RAM
• Native upstream web search via NEMOCLAW_WEB_SEARCH_PROVIDER, BRAVE_API_KEY, and TAVILY_API_KEY
• Optional OpenAI-compatible HTTP API on /v1/* via NEMOCLAW_OPENAI_HTTP_ENABLED=1
• Backup, restore, validation, and deployment manifest scripts

What the Patches Do

scripts/apply-patches.sh applies only environment-driven overlays:

Overlay	Trigger	Purpose
patches/fragments/dockerfile-integrations	NEMOCLAW_OPENAI_HTTP_ENABLED=1	Deep-merge cookbook-only OpenAI-compatible HTTP config into openclaw.json before the upstream integrity hash is pinned

There are no longer cookbook patches for sandbox-installed coding-agent tools, OpenShell version pinning, OpenClaw version overrides, web search, or generic git/plugin setup. Those experiments were removed or delegated to upstream.

When Upstream Changes

Validate against current upstream before rebuilding a live sandbox:

./scripts/validate-patches.sh

If validation fails, inspect what changed upstream and update the smallest affected overlay. If upstream now provides the capability, delete the cookbook overlay instead of carrying it forward. Update UPSTREAM.md only after a revised cookbook has been verified with an end-to-end deployment.

Backup and Restore

~/nemoclaw-cookbook/scripts/backup-full.sh backup <sandbox>
~/nemoclaw-cookbook/scripts/backup-full.sh list
~/nemoclaw-cookbook/scripts/backup-full.sh restore <sandbox>
~/nemoclaw-cookbook/scripts/backup-full.sh restore <sandbox> '' workspace
~/nemoclaw-cookbook/scripts/backup-full.sh restore <sandbox> '' sessions

Replace <sandbox> with your sandbox name, usually my-assistant.

Upgrading

The safe manual flow is:

~/nemoclaw-cookbook/scripts/backup-full.sh backup <sandbox>
cd ~/nemoclaw-cookbook && git pull --ff-only
./scripts/validate-patches.sh
cd ~/nemoclaw-cookbook && ./setup.sh

setup.sh updates upstream NemoClaw, lets upstream install the matching OpenShell version, reapplies only required cookbook overlays, and forces a sandbox rebuild when the recorded NemoClaw commit changed.

File Structure

.env.example          # Template for credentials and optional integrations
setup.sh              # Automated deployment script
patches/fragments/    # Small temporary overlays
scripts/
  apply-patches.sh    # Applies only needed overlays to upstream NemoClaw
  validate-patches.sh # Tests overlays against current upstream
  install-services.sh # nginx and optional browser-terminal services
  save-ui-url.sh      # Uses upstream URL/token commands; writes UI and /v1 client env files
  backup-full.sh      # Workspace, sessions, and skills backup/restore
BUILD.md              # From-scratch setup details
USE.md                # Day-to-day reference
UPSTREAM.md           # Current upstream compatibility and removal plan

Contributing

Start with CONTRIBUTING.md. The short version: search upstream first, keep patches narrow, document the removal condition, and delete cookbook code when upstream closes the gap.

License

This project is licensed under the Apache License 2.0.