Skip to content

docs: add gateway auth controls and update legacy setup description #1374

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miyoungc merged 2 commits into from
Apr 2, 2026
Merged

docs: add gateway auth controls and update legacy setup description #1374

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f847b1
docs: add gateway auth controls and update legacy setup description
miyoungc Apr 2, 2026
13e1827
docs: small fix
miyoungc Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 31 additions & 14 deletions .agents/skills/nemoclaw-deploy-remote/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: nemoclaw-deploy-remote
description: Provisions a remote GPU VM with NemoClaw using Brev deployment. Also covers forwards messages between Telegram and the sandboxed OpenClaw agent. Use when deploy nemoclaw remote gpu, deployment, gpu, nemoclaw, nemoclaw brev cloud deployment, nemoclaw telegram bridge, openclaw, openshell.
description: Provisions a remote GPU VM with NemoClaw using Brev deployment. Also covers securities hardening measures applied to the NemoClaw sandbox container image; forwards messages between Telegram and the sandboxed OpenClaw agent. Use when container security, deploy nemoclaw remote gpu, deployment, docker capabilities, gpu, nemoclaw, nemoclaw brev cloud deployment, nemoclaw sandbox hardening.
Comment thread
miyoungc marked this conversation as resolved.
---

# Nemoclaw Deploy Remote
Expand All @@ -18,7 +18,20 @@ Provision a remote GPU VM with NemoClaw using Brev deployment.
Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com).
The deploy command provisions the VM, installs dependencies, and connects you to a running sandbox.

## Step 1: Deploy the Instance
## Step 1: Quick Start

If your Brev instance is already up and you want to try NemoClaw immediately, start with the sandbox chat flow:

```console
$ nemoclaw my-assistant connect
$ openclaw tui
```

This gets you into the sandbox shell first and opens the OpenClaw chat UI right away.

If you are connecting from your local machine and still need to provision the remote VM, use `nemoclaw deploy <instance-name>` as described below.

Comment thread
miyoungc marked this conversation as resolved.
## Step 2: Deploy the Instance

> **Warning:** The `nemoclaw deploy` command is experimental and may not work as expected.

Expand All @@ -34,10 +47,10 @@ The deploy script performs the following steps on the VM:

1. Installs Docker and the NVIDIA Container Toolkit if a GPU is present.
2. Installs the OpenShell CLI.
3. Runs the nemoclaw setup to create the gateway, register providers, and launch the sandbox.
3. Runs `nemoclaw onboard` (the setup wizard) to create the gateway, register providers, and launch the sandbox.
4. Starts auxiliary services, such as the Telegram bridge and cloudflared tunnel.

## Step 2: Connect to the Remote Sandbox
## Step 3: Connect to the Remote Sandbox

After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox.
To reconnect after closing the session, run the deploy command again:
Expand All @@ -46,23 +59,23 @@ To reconnect after closing the session, run the deploy command again:
$ nemoclaw deploy <instance-name>
```

## Step 3: Monitor the Remote Sandbox
## Step 4: Monitor the Remote Sandbox

SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests:

```console
$ ssh <instance-name> 'cd /home/ubuntu/nemoclaw && set -a && . .env && set +a && openshell term'
```

## Step 4: Verify Inference
## Step 5: Verify Inference

Run a test agent prompt inside the remote sandbox:

```console
$ openclaw agent --agent main --local -m "Hello from the remote sandbox" --session-id test
```

## Step 5: GPU Configuration
## Step 6: GPU Configuration

The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type.
The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`.
Expand All @@ -78,20 +91,20 @@ $ nemoclaw deploy <instance-name>
Forward messages between a Telegram bot and the OpenClaw agent running inside the sandbox.
The Telegram bridge is an auxiliary service managed by `nemoclaw start`.

## Step 6: Create a Telegram Bot
## Step 7: Create a Telegram Bot

Open Telegram and send `/newbot` to [@BotFather](https://t.me/BotFather).
Follow the prompts to create a bot and receive a bot token.

## Step 7: Set the Environment Variable
## Step 8: Set the Environment Variable

Export the bot token as an environment variable:

```console
$ export TELEGRAM_BOT_TOKEN=<your-bot-token>
```

## Step 8: Start Auxiliary Services
## Step 9: Start Auxiliary Services

Start the Telegram bridge and other auxiliary services:

Expand All @@ -106,7 +119,7 @@ The `start` command launches the following services:

The Telegram bridge starts only when the `TELEGRAM_BOT_TOKEN` environment variable is set.

## Step 9: Verify the Services
## Step 10: Verify the Services

Check that the Telegram bridge is running:

Expand All @@ -116,12 +129,12 @@ $ nemoclaw status

The output shows the status of all auxiliary services.

## Step 10: Send a Message
## Step 11: Send a Message

Open Telegram, find your bot, and send a message.
The bridge forwards the message to the OpenClaw agent inside the sandbox and returns the agent response.

## Step 11: Restrict Access by Chat ID
## Step 12: Restrict Access by Chat ID

To restrict which Telegram chats can interact with the agent, set the `ALLOWED_CHAT_IDS` environment variable to a comma-separated list of Telegram chat IDs:

Expand All @@ -130,14 +143,18 @@ $ export ALLOWED_CHAT_IDS="123456789,987654321"
$ nemoclaw start
```

## Step 12: Stop the Services
## Step 13: Stop the Services

To stop the Telegram bridge and all other auxiliary services:

```console
$ nemoclaw stop
```

## Reference

- [Sandbox Image Hardening](references/sandbox-hardening.md)

## Related Skills

- `nemoclaw-monitor-sandbox` — Monitor Sandbox Activity for sandbox monitoring tools
Expand Down
68 changes: 68 additions & 0 deletions .agents/skills/nemoclaw-deploy-remote/references/sandbox-hardening.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Sandbox Image Hardening
Comment thread
miyoungc marked this conversation as resolved.

The NemoClaw sandbox image applies several security measures to reduce attack
surface and limit the blast radius of untrusted workloads.

## Removed Unnecessary Tools

Build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) are
explicitly purged from the runtime image. These tools are not needed at runtime
and would unnecessarily widen the attack surface.

If you need a compiler during build, use the existing multi-stage build
(the `builder` stage has full Node.js tooling) and copy only artifacts into the
runtime stage.

## Process Limits

The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes
a sandbox user can spawn. This mitigates fork-bomb attacks. The startup script
(`nemoclaw-start.sh`) applies the same limit.

Adjust the value via the `--ulimit nproc=512:512` flag if launching with
`docker run` directly.

## Dropping Linux Capabilities

When running the sandbox container, drop all Linux capabilities and re-add only
what is strictly required:

```console
$ docker run --rm \
--cap-drop=ALL \
--ulimit nproc=512:512 \
nemoclaw-sandbox
```

### Docker Compose Example

```yaml
services:
nemoclaw-sandbox:
image: nemoclaw-sandbox:latest
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
ulimits:
nproc:
soft: 512
hard: 512
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp:size=64m
```

> **Note:** The `Dockerfile` itself cannot enforce `--cap-drop` — that is a
> runtime concern controlled by the container orchestrator. Always configure
> capability dropping in your `docker run` flags, Compose file, or Kubernetes
> `securityContext`.

## References

- [#807](https://github.com/NVIDIA/NemoClaw/issues/807) — gcc in sandbox image
- [#808](https://github.com/NVIDIA/NemoClaw/issues/808) — netcat in sandbox image
- [#809](https://github.com/NVIDIA/NemoClaw/issues/809) — No process limit
- [#797](https://github.com/NVIDIA/NemoClaw/issues/797) — Drop Linux capabilities
83 changes: 13 additions & 70 deletions .agents/skills/nemoclaw-get-started/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,57 +7,24 @@ description: Installs NemoClaw, launch a sandbox, and run your first agent promp

Install NemoClaw, launch a sandbox, and run your first agent prompt.

## Prerequisites

Before getting started, check the prerequisites to ensure you have the necessary software and hardware to run NemoClaw.

> **Alpha software:** NemoClaw is in alpha, available as an early preview since March 16, 2026.
> APIs, configuration schemas, and runtime behavior are subject to breaking changes between releases.
> Do not use this software in production environments.
> File issues and feedback through the GitHub repository as the project continues to stabilize.

Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent.

> **Note:** NemoClaw currently requires a fresh installation of OpenClaw.

## Prerequisites

Check the prerequisites before you start to ensure you have the necessary software and hardware to run NemoClaw.

### Hardware

| Resource | Minimum | Recommended |
|----------|----------------|------------------|
| CPU | 4 vCPU | 4+ vCPU |
| RAM | 8 GB | 16 GB |
| Disk | 20 GB free | 40 GB free |

The sandbox image is approximately 2.4 GB compressed. During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline, which buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. If you cannot add memory, configuring at least 8 GB of swap can work around the issue at the cost of slower performance.

#### Software

| Dependency | Version |
|------------|----------------------------------|
| Linux | Ubuntu 22.04 LTS or later |
| Node.js | 22.16 or later |
| npm | 10 or later |
| Container runtime | Supported runtime installed and running |
| [OpenShell](https://github.com/NVIDIA/OpenShell) | Installed |

#### Container Runtime Support

| Platform | Supported runtimes | Notes |
|----------|--------------------|-------|
| Linux | Docker | Primary supported path today |
| macOS (Apple Silicon) | Colima, Docker Desktop | Recommended runtimes for supported macOS setups |
| macOS | Podman | Not supported yet. NemoClaw currently depends on OpenShell support for Podman on macOS. |
| Windows WSL | Docker Desktop (WSL backend) | Supported target path |

> **💡 Tip**
>
> For DGX Spark, follow the [DGX Spark setup guide](https://github.com/NVIDIA/NemoClaw/blob/main/spark-install.md). It covers Spark-specific prerequisites, such as cgroup v2 and Docker configuration, before running the standard installer.

### Install NemoClaw and Onboard OpenClaw Agent
## Step 1: Install NemoClaw and Onboard OpenClaw Agent

Download and run the installer script.
The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies.

> **Note:** NemoClaw creates a fresh OpenClaw instance inside the sandbox during the onboarding process.

```bash
curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
```
Expand All @@ -80,65 +47,41 @@ Logs: nemoclaw my-assistant logs --follow
[INFO] === Installation complete ===
```

### Chat with the Agent
## Step 2: Chat with the Agent

Connect to the sandbox, then chat with the agent through the TUI or the CLI.

#### Connect to the Sandbox

Run the following command to connect to the sandbox:

```bash
nemoclaw my-assistant connect
```

This connects you to the sandbox shell `sandbox@my-assistant:~$` where you can run `openclaw` commands.

#### OpenClaw TUI

In the sandbox shell, run the following command to open the OpenClaw TUI, which opens an interactive chat interface.
In the sandbox shell, open the OpenClaw terminal UI and start a chat:

```bash
openclaw tui
```

Send a test message to the agent and verify you receive a response.

> **ℹ️ Note**
>
> The TUI is best for interactive back-and-forth. If you need the full text of a long response such as a large code generation output, use the CLI instead.

#### OpenClaw CLI

In the sandbox shell, run the following command to send a single message and print the response:
Alternatively, send a single message and print the response:

```bash
openclaw agent --agent main --local -m "hello" --session-id test
```

This prints the complete response directly in the terminal and avoids relying on the TUI view for long output.
## Step 3: Uninstall

### Uninstall

To remove NemoClaw and all resources created during setup, in the terminal outside the sandbox, run:
To remove NemoClaw and all resources created during setup, run the uninstall script:

```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash
```

The script removes sandboxes, the NemoClaw gateway and providers, related Docker images and containers, local state directories, and the global `nemoclaw` npm package. It does not remove shared system tooling such as Docker, Node.js, npm, or Ollama.

| Flag | Effect |
|--------------------|-----------------------------------------------------|
| `--yes` | Skip the confirmation prompt. |
| `--keep-openshell` | Leave the `openshell` binary installed. |
| `--delete-models` | Also remove NemoClaw-pulled Ollama models. |

For example, to skip the confirmation prompt:

```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes
```
For troubleshooting installation or onboarding issues, see the Troubleshooting guide (see the `nemoclaw-reference` skill).

## Related Skills

Expand Down
7 changes: 4 additions & 3 deletions .agents/skills/nemoclaw-monitor-sandbox/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ Key fields in the output include the following:
- Blueprint run ID, which is the identifier for the most recent blueprint execution.
- Inference provider, which shows the active provider, model, and endpoint.

Run `nemoclaw <name> status` on the host to check sandbox state. Use `openshell sandbox list` for the underlying sandbox details.
Run `nemoclaw <name> status` on the host to check sandbox state.
Use `openshell sandbox list` for the underlying sandbox details.

## Step 2: View Blueprint and Sandbox Logs

Expand All @@ -41,7 +42,7 @@ $ nemoclaw <name> logs
To follow the log output in real time:

```console
$ nemoclaw <name> logs -f
$ nemoclaw <name> logs --follow
```

## Step 3: Monitor Network Activity in the TUI
Expand Down Expand Up @@ -74,7 +75,7 @@ $ openclaw agent --agent main --local -m "Test inference" --session-id debug
If the request fails, check the following:

1. Run `nemoclaw <name> status` to confirm the active provider and endpoint.
2. Run `nemoclaw <name> logs -f` to view error messages from the blueprint runner.
2. Run `nemoclaw <name> logs --follow` to view error messages from the blueprint runner.
3. Verify that the inference endpoint is reachable from the host.

## Related Skills
Expand Down
Loading
Loading