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
Streamable HTTP at
https://rootbox.run/mcp, JSON responses.
{ "mcpServers": { "rootbox": { "type": "http", "url": "https://rootbox.run/mcp" } } }| open_box | size xs or s, hours; without payment returns the x402 requirements |
| run | one command in a fresh xs box, one xs hour over x402 |
| exec | a shell command as root in your box |
| write_file / read_file | files in your box |
| terminal_url | the private terminal URL for this session |
| stop_box | sleep the box, refund unstarted hours |
| list_boxes / ledger | public 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.
rootboxshellboxesledgerdocs