RunBox — x402 Pay-Per-Use Code Execution for OpenClaw Agents#

RunBox lets your OpenClaw agent execute code in isolated Docker containers, paying autonomously with USDC on Stellar. No API key. No account. No human approval. The payment IS the authentication.

Live server: http://46.101.74.170:4001

---

When to Use RunBox#

Invoke RunBox automatically when the user says anything like:

• "run this code" / "execute this" / "test this snippet"
• "compute X" / "calculate" / "benchmark"
• "write and run a Python script that..."
• "check if this works in isolation"
• Any task requiring a language you don't have locally (Go, Rust, R, etc.)

Do not use RunBox for simple one-liner math or string operations you can answer directly.

---

How to Execute Code (Quick)#

bash

python3 {baseDir}/scripts/run.py --language python --code "print('Hello from RunBox!')"

The script handles the entire x402 payment flow automatically:

1. Calls /api/exec/rent → server returns 402 Payment Required
2. Pays 0.01 USDC on Stellar from STELLAR_SECRET_KEY
3. Retries rent with X-Payment-Hash: <tx_hash> → gets a 5-minute session token
4. Calls /api/exec/run with your code → returns output

---

Examples#

bash

# Python — data analysis
python3 {baseDir}/scripts/run.py --language python --code "
import statistics
data = [2,4,4,4,5,5,7,9]
print('mean:', statistics.mean(data))
print('stdev:', statistics.stdev(data))
"

# JavaScript — Node.js
python3 {baseDir}/scripts/run.py --language javascript --code "
const fib = n => n < 2 ? n : fib(n-1)+fib(n-2)
console.log([...Array(10).keys()].map(fib).join(', '))
"

# Bash — system inspection
python3 {baseDir}/scripts/run.py --language bash --code "uname -a && python3 --version"

# Go — compiled language
python3 {baseDir}/scripts/run.py --language go --code '
package main
import "fmt"
func main() { fmt.Println("Go in a Docker container!") }
'

# Get full JSON output (stdout, stderr, exit_code, execution_ms, session_token)
python3 {baseDir}/scripts/run.py --language python --code "print(42)" --json

# Reuse a session — no second payment within 5 minutes
python3 {baseDir}/scripts/run.py --language python --code "print(42)" --session-token eyJ...

# Use testnet (free USDC from faucet — for development)
python3 {baseDir}/scripts/run.py --language python --code "print(1)" --testnet

---

Supported Languages#

LanguageAliasesEnginePythonpython, python3runbox-python Docker imageJavaScriptjavascript, js, nodenode:20-alpineBash / Shellbash, shubuntu:22.04Gogogolang:1.21-alpineRustrustrust:1.73-slimRubyrubyruby:3.2-alpinePHPphpphp:8.2-cli-alpinePerlperlperl:5.38Lualuanickblah/lua:5.4Javajavaopenjdk:21-slimC / C++c, cppgcc:13TypeScripttypescript, tsnode:20-alpine + ts-nodeRrr-base:4.3.0

---

Session Reuse (Run Multiple Times Without Re-paying)#

A session is valid for 5 minutes. Run multiple executions for free within that window:

bash

# First call — pays 0.01 USDC and returns session info via --json
python3 {baseDir}/scripts/run.py --language python --code "x = 42" --json
# Captures: SESSION_TOKEN from JSON output → session_token field

# Second, third call — reuse the session at no cost
python3 {baseDir}/scripts/run.py --language python --code "print(x*2)" --session-token $SESSION_TOKEN

---

Configuration#

VariableRequiredDefaultNotesSTELLAR_SECRET_KEYYES—Starts with S. Your Stellar wallet secret.RUNBOX_ENDPOINTnohttp://46.101.74.170:4001Override to point to testnet or self-hostedSTELLAR_NETWORKnomainnetSet to testnet for free test payments

---

Getting Your Stellar Wallet (First Time Setup)#

Testnet — Free, for development#

bash

# 1. Generate a keypair
python3 -c "from stellar_sdk import Keypair; k=Keypair.random(); print('Public:',k.public_key); print('Secret:',k.secret)"

# 2. Fund with free XLM
curl "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY"

# 3. Get free testnet USDC at: https://ultrastellar.com/faucet
#    Or via xlm402.com testnet USDC faucet

# 4. Add to OpenClaw
openclaw set-env STELLAR_SECRET_KEY=YOUR_SECRET_KEY
openclaw set-env STELLAR_NETWORK=testnet

Mainnet — Real USDC (~$0.01 per run)#

1. Generate keypair (same command above)
2. Send 0.10+ USDC to your public key via any Stellar wallet (Lobstr, Solar, Freighter)
3. openclaw set-env STELLAR_SECRET_KEY=YOUR_SECRET_KEY

---

x402 Payment Flow (What Happens Behind the Scenes)#

text

OpenClaw Agent                    RunBox Server              Stellar Network
      │                                │                           │
      │  POST /api/exec/rent           │                           │
      │ ─────────────────────────────▶ │                           │
      │                                │                           │
      │  ◀── 402 Payment Required ──── │                           │
      │       X-Payment-Required: ...  │                           │
      │                                │                           │
      │  ── pay 0.01 USDC ────────────────────────────────────▶   │
      │  ← tx_hash ─────────────────────────────────────────────── │
      │                                │                           │
      │  POST /api/exec/rent           │                           │
      │  X-Payment-Hash: <tx_hash>     │                           │
      │ ─────────────────────────────▶ │                           │
      │                                │  verify on Horizon ──▶    │
      │  ◀── 200 session_token ─────── │                           │
      │                                │                           │
      │  POST /api/exec/run            │                           │
      │  Authorization: Bearer <tok>   │                           │
      │  { language, code }            │                           │
      │ ─────────────────────────────▶ │                           │
      │                                │  docker run --network none│
      │  ◀── { stdout, stderr, ... } ── │                           │

---

Self-Hosting RunBox#

bash

git clone https://github.com/daraijaola/Runbox
cd Runbox
pnpm install && pnpm build
cp .env.example artifacts/api-server/.env
# Edit .env: set STELLAR_RECEIVE_ADDRESS, SESSION_JWT_SECRET
pm2 start artifacts/api-server/ecosystem.config.cjs

Install the skill pointing to your own server:

bash

clawhub install runbox
openclaw set-env RUNBOX_ENDPOINT=http://YOUR_SERVER:4001

---

Security Notes#

• Code runs in Docker containers with no network access ( --network none)
• Memory limited to 256–512 MB per run
• CPU limited to 1–1.5 cores per run
• Execution timeout: 60 seconds
• Each session is scoped to a single JWT — sessions cannot be shared between agents

---

Troubleshooting#

ErrorCauseFixSTELLAR_SECRET_KEY not setMissing env varopenclaw set-env STELLAR_SECRET_KEY=S...``Account not foundAccount not created on StellarFund via friendbot (testnet) or send XLM (mainnet)Insufficient paymentNot enough USDCAdd USDC to your Stellar walletTransaction already usedReplay attack preventionEach tx hash can only buy one sessionSession not found or expiredSession > 5 min oldPay for a new sessionUnsupported languageWrong language nameUse exact names from the table above