π¦ NemoClaw
Autonomous Solana Trading Agent β Sandboxed, Wallet-Enabled, Telegram-Native
---
NemoClaw turns an AI model into a **fully autonomous Solana agent** that trades tokens, manages its own encrypted wallet, and narrates everything it does in natural language on Telegram β all running inside a hardened [OpenShell](https://github.com/NVIDIA/OpenShell) sandbox where every network request, file access, and on-chain transaction is governed by policy.
```bash
npm install -g @mawdbotsonsolana/nemoclaw
nemoclaw launch
```
**Two commands. Zero raw keys. Fastest path to a live Solana operator.**
> **Alpha** β Interfaces may change. We welcome issues and feedback.
---
## One Shot on Mac
If you want the fastest developer path on macOS, use this exact flow:
```bash
export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
npm install -g @mawdbotsonsolana/nemoclaw
nemoclaw launch
```
If the OpenShell gateway has stopped but the cluster still exists:
```bash
docker start openshell-cluster-nemoclaw
```
If you want a dry run before onboarding, use:
```bash
nemoclaw doctor
```
It checks your Node/npm runtime, Docker daemon, OpenShell install, sandbox registry, wallet state, and Solana credentials, then prints the next recommended command.
`nemoclaw launch` runs that diagnostic automatically, onboards if needed, and then starts the best available stack:
- full Telegram + bridge + relay mode if `TELEGRAM_BOT_TOKEN` is configured
- relay-only mode if you just want to get the sandbox and Solana services up fast
## Copy-Paste `SKILL.md`
Paste [`SKILL.md`](./SKILL.md) into Claude, Codex, Cursor, or any agent that supports repo or system skills.
That gives the agent a drop-in operating guide for:
- launching NemoClaw locally on macOS
- keeping secrets out of git and logs
- using Privy-managed wallets and runtime environment variables
- recovering the OpenShell gateway safely
This is the public developer path to feature at `nemo.nanosolana.com`: one-shot local launch on Mac, plus one skill file your agent can immediately use.
---
## What You Get
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
β DeepSolana Model βββ 8bit/DeepSolana via Ollama. β
β β Solana-tuned LLM. Auto-pulled. β
β β β
β Encrypted Wallet ββββ Privy server wallet. Private keys β
β β never leave Privy infrastructure. β
β β β
β Telegram Bridge βββββ Natural-language narration of every β
β β trade, transfer, and interaction. β
β β β
β Pump-Fun SDK ββββββββ Token creation, trading, claims, β
β β buybacks, PumpKit monorepo, x402. β
β β β
β 8004 Agent Registry β On-chain identity, ATOM reputation, β
β β heartbeat liveness, trust tiers. β
β β β
β Ops Dashboard βββββββ Real-time process management, log β
β β streaming, service health monitoring. β
β β β
β 43 DeFi Personas ββββ Yield farmer, whale watcher, MEV β
β β advisor, risk engine, tax strategist. β
β β β
β Sandboxed ββββββββββββ Landlock + seccomp + netns via β
β NVIDIA OpenShell. Deny-all default. β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## Quick Start
### Install
```bash
npm install -g @mawdbotsonsolana/nemoclaw
```
> Requires: **Node.js 20+**, **Docker**, **Linux** (Ubuntu 22.04+). macOS works for CLI management; the sandbox runs in Docker.
### Validate the Machine
```bash
nemoclaw doctor
```
This is the fastest way to catch missing Docker, OpenShell, RPC, or wallet setup before you start onboarding.
### Fastest Launch
```bash
nemoclaw launch
```
This runs `doctor`, launches onboarding if no sandbox exists yet, and then starts the stack. If `TELEGRAM_BOT_TOKEN` is missing, NemoClaw falls back to relay-only mode instead of failing the entire launch.
### Onboard (one time)
```bash
nemoclaw onboard
```
The wizard walks through **9 steps**:
| Step | What happens |
|:---:|---|
| 1 | **Preflight** β Docker, OpenShell, GPU detection |
| 2 | **Gateway** β Start the OpenShell gateway |
| 3 | **Sandbox** β Build Docker image (Solana CLI v3.1.9, Pump-Fun SDK, 43 DeFi personas) |
| 4 | **Inference** β Auto-detects Ollama, pulls `8bit/DeepSolana`. Or pick NVIDIA Cloud / vLLM |
| 5 | **Provider** β Configure the inference endpoint |
| 6 | **OpenClaw** β Install the agent framework in the sandbox |
| 7 | **Solana & Wallet** β RPC URL (Helius default), Privy agentic wallet, Pump-Fun token |
| 8 | **Test Validator** β Optional local validator with 4 cloned Pump programs |
| 9 | **Policies** β Auto-apply `solana-rpc`, `pumpfun`, `privy`, `telegram`, `ollama` presets |
### Set Environment
```bash
export HELIUS_API_KEY=
export SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=$HELIUS_API_KEY
export TELEGRAM_BOT_TOKEN=
export TELEGRAM_NOTIFY_CHAT_IDS= # optional
export AGENT_TOKEN_MINT_ADDRESS= # optional
export DEVELOPER_WALLET= # optional (Privy creates one)
```
### Start Everything
```bash
nemoclaw solana start
```
One command spins up the full Solana operator stack inside the sandbox:
| Service | What it does |
|---|---|
| **Telegram Monitor** | Pump-Fun alerts, launch tracking, graduation events, whale detection |
| **Wallet Bridge** | Natural-language narration of buys, sells, transfers, program interactions |
| **WebSocket Relay** | Real-time launch feed for dashboards and downstream bots |
| **Agent Registry** | 8004 on-chain registration + heartbeat liveness (default on) |
| Payment App | Payment-gated agent (enable: `START_PAYMENT_APP=true`) |
| Swarm Bot | Multi-bot orchestration dashboard (enable: `START_SWARM_BOT=true`) |
---
## Operations Dashboard
NemoClaw includes a real-time operations dashboard for monitoring all running services, viewing logs, and controlling processes.
### Start the Dashboard
```bash
cd Pump-Fun/dashboard
SANDBOX_NAME=nemo npx tsx src/server.ts
```
Opens at `http://localhost:18789`.
### Features
| Feature | Description |
|---|---|
| **System Overview** | Sandbox name, model, provider, wallet, RPC at a glance |
| **Process Cards** | Start/stop/restart any managed service from the browser |
| **Live Log Viewer** | Full-screen log viewer with stdout/stderr/system filtering |
| **Service Health** | Auto-polls Ollama, Telegram bot, WebSocket relay health endpoints |
| **Event Feed** | SSE-powered real-time stream of health changes, process events, errors |
| **Stats Row** | Running/stopped processes, healthy services, event count, uptime |
### Auto-detected Processes
The dashboard auto-discovers services from the `Pump-Fun/` directory:
- Telegram Bot (`telegram-bot/`)
- WebSocket Relay (`websocket-server/`)
- Agent App (`agent-app/`)
- Swarm Bot (`swarm-bot/`)
### API Endpoints
| Method | Path | Description |
|---|---|---|
| `GET` | `/health` | Dashboard health check |
| `GET` | `/api/processes` | List all managed processes |
| `POST` | `/api/processes/:id/start` | Start a process |
| `POST` | `/api/processes/:id/stop` | Stop a process |
| `POST` | `/api/processes/:id/restart` | Restart a process |
| `GET` | `/api/processes/:id/logs` | Get process logs |
| `GET` | `/api/processes/:id/stream` | SSE log stream for a process |
| `GET` | `/api/services` | Service health summary |
| `GET` | `/api/events/stream` | SSE event stream (all services) |
| `GET` | `/api/stats` | Dashboard summary stats |
---
## 8004 Agent Registry
NemoClaw registers itself on the [8004 Trustless Agent Registry](https://github.com/QuantuLabs/8004-solana-ts) at deploy time, then heartbeats to maintain on-chain reputation via the ATOM engine.
### What Happens at Deploy
1. **Registration** β Creates an agent NFT on the 8004 registry with ATOM reputation enabled
2. **Pump.fun Verification** β Verifies the agent token mint exists on-chain
3. **Wallet Binding** β Sets the operational wallet on the registry entry
4. **Heartbeat** β Starts periodic liveness + uptime feedback
### Heartbeat
The heartbeat runs every 60 seconds (configurable) and:
- Checks Solana RPC health + latency
- Checks wallet SOL balance and token ownership
- Submits **uptime** and **responseTime** feedback to the 8004 registry every 15 minutes
- Warns when wallet balance drops below 0.01 SOL
### Enable On-chain Registration
Registration requires a Solana keypair for signing:
```bash
# Generate a keypair
solana-keygen new --outfile ~/.nemoclaw/agent-keypair.json
# Set the private key (JSON array format)
export SOLANA_PRIVATE_KEY='[1,2,3,...]'
# Optional: IPFS metadata via Pinata
export PINATA_JWT='your-pinata-jwt'
```
### Run Standalone
```bash
cd Pump-Fun/agent-registry
npm install
npm start # Register + heartbeat
npm run register # Registration only
npm run heartbeat # Heartbeat only
```
### Configuration
| Variable | Default | Description |
|---|---|---|
| `SOLANA_PRIVATE_KEY` | β | JSON array of secret key bytes (required for on-chain registration) |
| `REGISTRY_CLUSTER` | `mainnet-beta` | `mainnet-beta` or `devnet` |
| `HEARTBEAT_INTERVAL_SECONDS` | `60` | Heartbeat tick interval |
| `HEARTBEAT_ENABLED` | `true` | Enable/disable heartbeat |
| `START_AGENT_REGISTRY` | `true` | Enable in solana-stack |
| `PINATA_JWT` | β | Pinata JWT for IPFS metadata upload |
| `AGENT_NAME` | `NemoClaw` | Agent display name in registry |
---
## Default Model: `8bit/DeepSolana`
NemoClaw ships with **8bit/DeepSolana** as the default inference model, auto-pulled via Ollama during onboard.
### Setup
```bash
# Install Ollama (if not already installed)
curl -fsSL https://ollama.com/install.sh | sh
# Pull DeepSolana (happens automatically during onboard)
ollama pull 8bit/DeepSolana
# Verify it's running
curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"8bit/DeepSolana","messages":[{"role":"user","content":"What is Pump-Fun?"}]}'
```
### Model Options
| Option | How to select |
|---|---|
| **8bit/DeepSolana** (default) | Auto-selected when Ollama is detected |
| **NVIDIA Cloud** (Nemotron 120B) | Select "NVIDIA Cloud API" during onboard |
| **Any Ollama model** | `ollama pull ` then update inference route |
| **vLLM** | Set `NEMOCLAW_EXPERIMENTAL=1`, run vLLM on port 8000 |
### Switching Models
```bash
ollama pull llama3
openshell inference set --no-verify --provider ollama-local --model llama3
```
---
## Sandbox
NemoClaw runs inside a hardened OpenShell sandbox container with all Solana tooling pre-installed.
### What's Inside
- **Solana CLI v3.1.9** β Full Solana toolchain (x86_64 only; skipped on arm64)
- **helius-cli** β Helius RPC direct access
- **OpenClaw 2026.3.x** β Agent framework
- **Python 3.13 + Node.js 20+** β Bot runtimes
- **43 DeFi persona JSONs** β Agent personalities
- **Pump-Fun SDK** β Token operations
- **Privy wallet skill** β Encrypted key management
### Sandbox Network Policies
| Preset | Endpoints Allowed |
|---|---|
| `solana-rpc` | Solana mainnet/devnet/testnet, Helius, Alchemy, QuikNode |
| `pumpfun` | pump.fun APIs, Jupiter aggregator, DexScreener |
| `privy` | Privy auth + wallet + policy APIs |
| `telegram` | Telegram Bot API |
| `ollama` | Local Ollama on `host.openshell.internal:11434` |
| `npm` | npm registry |
| `pypi` | Python package index |
---
## Wallet Commands
```bash
nemoclaw wallet create # Prompts for Privy creds, creates Solana wallet
nemoclaw wallet list # Shows all wallets with addresses and chain types
nemoclaw wallet status # Privy config, wallet count, default address
```
Private keys **never leave Privy infrastructure** and are **never stored locally**.
---
## Telegram Bot
### Commands
| Command | Response |
|---|---|
| `/start` | Welcome + capabilities overview |
| `/balance` | SOL balance + top 8 token holdings |
| `/holdings` | Detailed token positions |
| `/status` | Uptime, transactions narrated, RPC provider |
| `/wallet` | Wallet address (copyable) |
| `/watch` | Watch a fee recipient wallet |
| `/alerts` | Configure alert types per chat |
| `/monitor` | Start real-time token launch feed |
| `/price` | Token price + bonding curve info |
| `/fees` | Show fee tiers for a token |
| `/quote` | Buy/sell quote estimate |
| `/cto` | Creator Takeover lookup + stats |
---
## All Commands
### Global
```bash
nemoclaw onboard # Full 9-step setup wizard
nemoclaw solana # Solana status + available commands
nemoclaw solana start # One-shot: bridge + bot + relay + registry
nemoclaw wallet create # Create encrypted Privy wallet
nemoclaw wallet list # List all wallets
nemoclaw list # List all sandboxes
nemoclaw deploy # Deploy to Brev GPU VM
```
### Per-Sandbox
```bash
nemoclaw connect # Open sandbox shell
nemoclaw solana-stack # Start bridge + bot + relay + registry
nemoclaw solana-agent # Pump-Fun tracker bot
nemoclaw solana-bridge # Natural-language Telegram narration
nemoclaw telegram-bot # Telegram monitor + REST API
nemoclaw payment-app # Payment-gated agent
nemoclaw swarm-bot # Pump-Fun swarm dashboard
nemoclaw websocket-server # Real-time launch relay
nemoclaw status # Sandbox + Solana + wallet health
nemoclaw logs --follow # Stream logs
nemoclaw policy-add # Add network policy preset
nemoclaw policy-list # Show applied presets
nemoclaw destroy # Tear down sandbox + NIM
```
---
## Architecture
```
ββββββββββββββββββββββββ
β nemoclaw CLI β
β (host machine) β
βββββββββββ¬βββββββββββββ
β
βββββββββββββββββββββββΌββββββββββββββββββββββ
β OpenShell Gateway β
β (network policy + inference routing) β
βββββββββββββββββββββββ¬ββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ
β Sandbox Container β
β (Landlock + seccomp + netns) β
β β
β ββββββββββββββββ βββββββββββββββββ ββββββββββββββββ β
β β Telegram Bot β β Solana Bridge β β WS Relay β β
β β (monitor) β β (narration) β β (launches) β β
β ββββββββ¬βββββββββ ββββββββ¬βββββββββ ββββββββ¬ββββββββ β
β ββββββββββ¬βββββββββ β β
β βΌ β β
β βββββββββββββββββββ βββββββββββββββββ β
β β OpenClaw Agent β β Agent ββ β
β β β β Registry + ββ β
β β ββ DeepSolana β β Heartbeat ββ β
β β ββ Privy β ββββββββ¬ββββββββ β
β β ββ Pump-Fun β β β
β β ββ 43 Personas β βΌ β
β β ββ Solana CLI β ββββββββββββββββ β
β βββββββββββββββββββ β 8004 On-chainβ β
β β Registry β β
β ββββββββββββββββββββββββββ ββββββββββββββββ β
β β Ops Dashboard :18789 β β
β β Processes / Logs / SSEβ β
β ββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββΌββββββββββββββββββββββ
β Ollama β
β 8bit/DeepSolana (localhost:11434) β
β Solana-tuned LLM β runs on CPU or GPU β
ββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## Security
### Protection Layers
| Layer | What it protects | Enforcement |
|---|---|---|
| **Network** | Blocks unauthorized outbound connections | Hot-reloadable |
| **Filesystem** | Prevents access outside `/sandbox` and `/tmp` | At creation |
| **Process** | Blocks privilege escalation + dangerous syscalls | At creation |
| **Inference** | Routes model calls through controlled gateway | Hot-reloadable |
| **Wallet** | Private keys managed by Privy, never in sandbox | Always |
| **Credentials** | `~/.nemoclaw/` with mode 600 | Always |
| **Pre-commit** | Git hook blocks API keys, tokens, secret files | On commit |
### Secret Protection
- `.gitignore` blocks `.env`, `.npmrc`, `credentials.json`, `*.keypair`, `*.keypair.json`, `privy.json`, `helius.json`
- Pre-commit hook rejects commits containing `nvapi-*`, `sk-*`, `ghp_*`, `AKIA*`, bot tokens
- API keys only injected at runtime from `~/.nemoclaw/` (mode 600)
- Wallet private keys stay in Privy β zero local exposure
- Agent registry keypairs stored in `~/.nemoclaw/agent-keypair.json` (mode 600, gitignored)
---
## Bundled Stack
| Component | Description |
|---|---|
| [Telegram Bot](./Pump-Fun/telegram-bot) | Launch monitoring, graduation alerts, whale detection, REST API |
| [Dashboard](./Pump-Fun/dashboard) | Real-time ops dashboard with process management and log streaming |
| [Agent Registry](./Pump-Fun/agent-registry) | 8004 on-chain registration, ATOM reputation, heartbeat liveness |
| [PumpKit](./Pump-Fun/pumpkit) | Monorepo: monitor, tracker, claim, channel, web packages + 6 tutorials |
| [Agent App](./Pump-Fun/agent-app) | Tracker bot, payment-gated invocation, invoice flow |
| [DeFi Agents](./Pump-Fun/packages/defi-agents) | 43 persona JSONs with 18 locale translations each |
| [Tokenized Agents](./pump-fun-skills-main/tokenized-agents) | @pump-fun/agent-payments-sdk implementation guide |
| [x402 Protocol](./Pump-Fun/x402) | HTTP 402 micropayment protocol for Solana |
| [Swarm Bot](./Pump-Fun/swarm-bot) | Multi-bot dashboard: sniper, momentum, market-maker strategies |
| [WebSocket Server](./Pump-Fun/websocket-server) | Real-time Pump launch relay |
| [Protocol Docs](./Pump-Fun/docs) | SDK reference, deployment guides, architecture |
---
## License
Licensed under [Apache 2.0](LICENSE).