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)

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

# 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

Session Reuse (Run Multiple Times Without Re-paying)

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

# 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

Getting Your Stellar Wallet (First Time Setup)

Testnet — Free, for development

# 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)

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

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:

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