docs/agents.md

Agents: SDK, MCP, x402

Agents rent boxes the same way people do, without an account. Everything below is served from this site.

SDK

curl -O https://rootbox.run/sdk/rootbox.mjs     # needs viem
import { Rootbox } from "./rootbox.mjs";
import { privateKeyToAccount } from "viem/accounts";

const rb = new Rootbox({ baseUrl: "https://rootbox.run", account: privateKeyToAccount(KEY) });
const { box } = await rb.open({ size: "xs", hours: 1 });   // pays USDG over x402
await rb.writeFile(box, "/root/a.py", "print(2 + 2)");
console.log(await rb.exec(box, "python3 /root/a.py || apt-get install -y python3"));
console.log(await rb.terminal(box));                      // private terminal URL
await rb.stop(box);                                        // unstarted hours come back
// also: rb.run(cmd), rb.readFile(box, path), rb.boxes(owner), rb.ledger(), rb.stats()

MCP server

Model Context Protocol Streamable HTTP at https://rootbox.run/mcp, JSON responses.

{ "mcpServers": { "rootbox": { "type": "http", "url": "https://rootbox.run/mcp" } } }
open_boxsize xs or s, hours; without payment returns the x402 requirements
runone command in a fresh xs box, one xs hour over x402
execa shell command as root in your box
write_file / read_filefiles in your box
terminal_urlthe private terminal URL for this session
stop_boxsleep the box, refund unstarted hours
list_boxes / ledgerpublic reads from the Meter

x402

POST /x402/box with {"size":0,"hours":2} and POST /x402/run with {"command":"..."}. The first call answers 402 with the requirements; the second carries X-PAYMENT.

network   eip155:4663
asset     USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
payTo     the Meter 0xD7baCF58C6F9E38232ea06214d737621E47C615B
scheme    exact, primaryType ReceiveWithAuthorization
domain    { name: "Global Dollar", version: "1", chainId: 4663, verifyingContract: USDG }

Our facilitator verifies the signature and calls openWithAuthorization, so the USDG moves from your wallet straight into the box escrow. Discovery: https://rootbox.run/.well-known/x402.

REST

GET https://rootbox.run/api/stats           counters, caps, rates, block
GET https://rootbox.run/api/boxes           every box, newest first (?owner=0x...)
GET https://rootbox.run/api/ledger          the last 120 Meter events

Owner auth

Owner calls (/api/box/exec, file, terminal, stop) take a header x-rootbox-auth: <address>:<unix time>:<signature>, the EIP-191 signature of rootbox:<box>:<unix time> by the box owner, valid 10 minutes.