RunBox — Paid Code Execution for AI Agents

Dev Tools

Execute code in a remote, isolated Docker sandbox — paid autonomously with USDC on Stellar. Use when the user asks to run, execute, test, or benchmark code in any language, especially when a clean isolated environment is needed. Supports Python, JavaScript, Bash, Go, Rust, Ruby, PHP, Perl, Lua, Java, C, C++, TypeScript, and R.

Install

openclaw skills install runbox

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:

Calls /api/exec/rent → server returns 402 Payment Required
Pays 0.01 USDC on Stellar from STELLAR_SECRET_KEY
Retries rent with X-Payment-Hash: <tx_hash> → gets a 5-minute session token
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

Language	Aliases	Engine
Python	`python`, `python3`	runbox-python Docker image
JavaScript	`javascript`, `js`, `node`	node:20-alpine
Bash / Shell	`bash`, `sh`	ubuntu:22.04
Go	`go`	golang:1.21-alpine
Rust	`rust`	rust:1.73-slim
Ruby	`ruby`	ruby:3.2-alpine
PHP	`php`	php:8.2-cli-alpine
Perl	`perl`	perl:5.38
Lua	`lua`	nickblah/lua:5.4
Java	`java`	openjdk:21-slim
C / C++	`c`, `cpp`	gcc:13
TypeScript	`typescript`, `ts`	node:20-alpine + ts-node
R	`r`	r-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:

# 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

Variable	Required	Default	Notes
`STELLAR_SECRET_KEY`	YES	—	Starts with `S`. Your Stellar wallet secret.
`RUNBOX_ENDPOINT`	no	`http://46.101.74.170:4001`	Override to point to testnet or self-hosted
`STELLAR_NETWORK`	no	`mainnet`	Set to `testnet` for free test payments

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)

Generate keypair (same command above)
Send 0.10+ USDC to your public key via any Stellar wallet (Lobstr, Solar, Freighter)
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

Error	Cause	Fix
`STELLAR_SECRET_KEY not set`	Missing env var	`openclaw set-env STELLAR_SECRET_KEY=S...`
`Account not found`	Account not created on Stellar	Fund via friendbot (testnet) or send XLM (mainnet)
`Insufficient payment`	Not enough USDC	Add USDC to your Stellar wallet
`Transaction already used`	Replay attack prevention	Each tx hash can only buy one session
`Session not found or expired`	Session > 5 min old	Pay for a new session
`Unsupported language`	Wrong language name	Use exact names from the table above