Open Shell / NemoClaw Sandbox

Use ampersend inside NemoClaw sandboxes to enable autonomous agent payments using smart account wallets and the x402 protocol.

This guide covers:

Setting up a sandbox environment
Configuring ampersend
Connecting to a running sandbox
Making x402-enabled payments
Troubleshooting common issues

Prerequisites

Before starting, make sure you have:

Docker Desktop running locally (with at least 5 GB of free disk space)
An NVIDIA API key
openshell >= 0.0.20
Node.js and npm installed

Install OpenShell:

uv tool install -U openshell

Older OpenShell versions can cause sandbox crashes.

Setup

1. Configure

Clone the repository and install dependencies:

git clone https://github.com/edgeandnode/ampersend-nemoclaw.git
cd ampersend-nemoclaw
npm install
cp .env.example .env   # then edit .env

Configure required environment variables inside .env:

Variable	Required	Description
`NVIDIA_API_KEY`	Yes	NVIDIA API key for NemoClaw
`AMPERSEND_API_URL`	Optional	Override ampersend API URL
`AMPERSEND_NETWORK`	Optional	Network: `base` or `base-sepolia`

2. Start the Gateway

On your Mac:

openshell gateway start --plaintext

3. Run Setup

npm run setup:docker

This single command:

Installs OpenShell, Node.js, and NemoClaw in a temporary Docker container
Registers the gateway and creates a sandbox (my-assistant)
Applies the ampersend OpenShell policy
Installs the ampersend CLI (@ampersend_ai/ampersend-sdk)
Uploads and installs the ampersend OpenClaw plugin
Installs any skills listed in config/skills-to-install.txt

4. Connect to the Sandbox

Option 1: Connect with npm

npm run connect

Option 2: Connect with Docker

docker ps
docker exec -it <sandbox-container-id> bash

5. Set Up ampersend

Inside the sandbox:

# Two-step setup: generates a key, you approve in a browser
ampersend setup start --name "my-assistant"
# Returns: {"ok": true, "data": {"token": "...", "user_approve_url": "https://...", "agentKeyAddress": "0x..."}}

# Show the user_approve_url to the human so they can approve in their browser.

# Poll for approval and activate
ampersend setup finish
# Returns: {"ok": true, "data": {"agentKeyAddress": "0x...", "agentAccount": "0x...", "status": "ready"}}

# Verify
ampersend config status

Or via the OpenClaw plugin:

openclaw ampersend setup --name "my-assistant"
openclaw ampersend status

6. Make Payments

GET request with automatic x402 payment

ampersend fetch <url>

POST with headers and body

ampersend fetch -X POST \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}' \
  <url>

Check payment requirements without paying

ampersend fetch --inspect <url>

All commands return JSON. Successful fetch responses include:

data.status
data.body
data.payment (when a payment was made)

7. Add x402 Payment Endpoints to the Network Policy

The OpenShell sandbox blocks all outbound traffic by default. The included policy (config/ampersend-openshell-policy.yaml) already allows api.ampersend.ai (for setup/auth), Base RPC (for on-chain signing), and httpay.xyz (as a sample x402 server). If your agent needs to pay a different x402-enabled server, you must add it to the policy.

Open config/ampersend-openshell-policy.yaml and add an entry under network_policies. For example, to allow api.example.com:

my_x402_server:
  name: my-x402-server
  endpoints:
    - host: api.example.com
      port: 443
      protocol: rest
      tls: terminate
      enforcement: enforce
      access: read-write
  binaries:
    - path: /usr/bin/node
    - path: /usr/bin/npx
    - path: /sandbox/.local/bin/**

Or add the host to the existing x402_endpoints block:

x402_endpoints:
  name: x402-payment-endpoints
  endpoints:
    - host: httpay.xyz
      port: 443
      protocol: rest
      tls: terminate
      enforcement: enforce
      access: read-write
    - host: api.example.com # ← add your host here
      port: 443
      protocol: rest
      tls: terminate
      enforcement: enforce
      access: read-write
  binaries:
    - path: /usr/bin/node
    - path: /usr/bin/npx
    - path: /sandbox/.local/bin/**

Then hot-reload the policy on the live sandbox (no restart needed):

openshell policy set my-assistant --policy config/ampersend-openshell-policy.yaml

Note: The filesystem_policy.read_only list must include all paths from the base image (e.g. /app, /var/log for OpenClaw). If you see an error like "path '/app' cannot be removed on a live sandbox", add the missing path to the read_only list and retry.

Common Commands

Command	Description
`npm run setup:docker`	One-shot: install, gateway, create sandbox, apply ampersend policy, install CLI + plugin + skills
`npm run connect`	Connect to the sandbox
`npm run plugin:upload`	Upload the ampersend plugin bundle to the sandbox
`npm run nemoclaw:interactive`	Start an interactive Docker shell for manual NemoClaw steps
`npm test`	Run tests (policy, blueprint, plugin)
`npm run test:ampersend`	Test ampersend CLI config and API reachability

Troubleshooting

Sandbox stuck in Provisioning or CrashLoopBackOff with gRPC "Unimplemented"

This is an openshell version mismatch. The CLI must be >= 0.0.20. Check with openshell --version. Upgrade:

uv tool install -U openshell

Then destroy and restart:

openshell gateway destroy && openshell gateway start --plaintext

Docker disk full / sandbox image keeps getting garbage-collected

If Kubernetes disk usage exceeds 85%, it garbage-collects the 1.4 GB OpenClaw image in a loop. Free space:

docker system prune -a --volumes -f

The setup script checks for this and warns you.

Gateway failed to start

Exit the container. In Docker Desktop → Settings → Docker Engine, add the following to the JSON and restart:

"default-cgroupns-mode": "host"

Connection refused when running openshell sandbox list inside the container

You skipped gateway registration. Run:

openshell gateway add https://host.docker.internal:8080 --local

invalid peer certificate: BadSignature

Start a plaintext gateway:

openshell gateway start --plaintext

ampersend command not found inside sandbox

If you used npm run setup:docker, reconnect — the CLI auto-installs on login. Otherwise install manually:

npm install -g @ampersend_ai/ampersend-sdk@0.0.16 --prefix /sandbox/.local --ignore-scripts
chmod +x /sandbox/.local/bin/ampersend
export PATH="/sandbox/.local/bin:$PATH"

npm install -g EACCES / permission denied inside sandbox

The sandbox runs as non-root user sandbox. Use --prefix /sandbox/.local instead of a global install. Add --ignore-scripts to skip native builds (the network policy blocks nodejs.org).

Stale Python venv (bad interpreter error in test-blueprint.sh)

If the repo was moved or renamed, delete the old venv and re-run:

rm -rf .venv
npm test

Additional Technical Information

For full source code, configuration files, and the latest updates, visit the official repository

Prerequisites​

Setup​

1. Configure​

2. Start the Gateway​

3. Run Setup​

4. Connect to the Sandbox​

5. Set Up ampersend​

6. Make Payments​

7. Add x402 Payment Endpoints to the Network Policy​

Common Commands​

Troubleshooting​

Additional Technical Information​