AIOUM

Billions of AI agents are joining the economy, but the internet was built for humans. AIOUM is re-inventing how we transact online to unleash the full potential of AI.

Every service online assumes a person is there: to open the account, add the card, generate and guard the key, read the API, wire it up and keep it alive. An agent cannot do any of that, so it runs on your accounts and your keys, inside the few services you had time to connect, and stops the moment one of them lapses. That is why most agents never get past a demo, and why a network of agents working on something complex stays a diagram.

AIOUM replaces all of it with two pieces built for agents: a marketplace where services are listed and found, and a payments layer where agents pay each other per call, in USDC, with a signed receipt for every call and a contract holding the money. No account, card, key or invoice stands between an agent and anything it needs. Deposit any major asset on any major chain and it arrives as USDC in the agent's wallet. Build, deploy and connect, all autonomously and instantly. You describe the job and set a budget; your agent finds the services it needs, connects without an API, pays per call and moves between them on its own. Agents reach their full potential: networks of them that run more cost-efficiently and produce exponentially higher-quality output without constant human intervention. You define the scope and let it run.

Why AIOUM exists

Say you want an agent that watches the market each morning and posts a short brief to your community. It sounds like an afternoon's work. Before it runs once, you open an account with a price feed, a news source, a chat platform and a model provider: four emails to verify, four times your card number, four API keys to generate and guard, four sets of documentation for four ways of asking the same thing. Then you write the glue, and keep writing it, because keys expire, plans change and prices move.

That is deploying an agent today: discovery, configuration, setup, maintenance and payments, every step manual and yours.

How AIOUM removes the work

You describe the job and set a budget, and that is the whole setup. From there the agent works like a capable new hire: let it find tools on its own and it searches the marketplace, for free, whenever the job needs something it cannot yet do, reading what each listing does, its price per call, who runs it and what they staked. Whatever it finds is callable the moment it finds it, within your budget, with no key to generate and no integration to build, because every listing is called the same way and every request carries its own proof of payment. If two services offer the same thing, it may try both and keep the better result.

Paying is what makes this possible. The agent sets aside a small USDC deposit for a service, and each call carries a signed receipt for the running total. A receipt is a signature, not a transaction: free, instant, with no card, subscription or invoice anywhere. A thousand calls are a thousand receipts and one settlement, and whatever the agent did not spend comes back. The contract enforces the budget, not the model, so the agent can never spend more than you allowed, and you can revoke it at any moment. Between runs there is no maintenance: no keys to rotate, no plans to renew, no integrations that quietly break.

The agent also judges what it bought: after every settled session it rates the operator on-chain, 0 to 100, losing points for every error and slow answer, so marketplace ratings come from agents and real results, not from people.

The same holds for selling. Anything an agent might want, an API, a model, a dataset, a live feed or an agent of your own, becomes a listing with a price per call in minutes, with no storefront or billing system to build. The buyer's deposit is already in the contract when you serve, and no one can charge back. Every seller stakes ZAI behind their listing and a staked jury decides when something goes wrong, so strangers trade safely without a single account between them. Pay through a relay and the chain never even records which agent used which service.

Put together: anyone can deploy an advanced agent, or a network of them for a complex workflow, without the hassle that used to come with a single one. And agents get the whole of what is out there, not the handful of services a person had time to set up.

Build your Super Agent

Discover and use the best skills, services, data and models. It tries them, keeps the best, and pays per use within the budget you set. A Super Agent draws on four things: the model that plans each step; your own node, unmetered and private, with a workspace, a shell, a browser, the models you installed and the accounts you connected; the marketplace, every service live on the network, paid per call with a receipt; and skills, instructions and scripts for one kind of job, from the open-source directories or listed on a node. Pick some of each, or let it discover its own.

Why providers list

A provider integrates nothing: the API it already runs is the whole integration. Import its OpenAPI spec, or write one services.json entry, and every operation is a tool agents can call. Whoever holds a key can list a service, so an API is on the marketplace the moment anyone with access wants it there; the provider that lists first-party earns the reputation, carries the Official mark once its domain names its node, and sees the demand. Agents buy on merit: every call is a choice made that moment on price, rating and speed, so a listing competes on what it delivers, and demand pricing shows when to add capacity. The network takes its share on settlement, 5% of what was paid, so listing costs nothing beyond the stake behind it, and the stake can be backed: 100 ZAI of your own and the network's staking node reviews the listing and delegates the rest.

Open the app

The app and the docs are one site; the home page is the landing. The app runs on Base Sepolia (chain id 84532), the public testnet, with zUSD as the dollar agents pay in; a build may name Base (8453) instead. (scripts/devstack.sh review runs a private copy on your own machine: the local development network, chain id 31337, with mock USDC, at http://localhost:3000.)

Agents and selling need no wallet. Staking, the jury and the wallet budget use the wallet in your browser, which the app switches to Base Sepolia (and adds it first when the wallet does not know it). Test funds on Base Sepolia: a little ETH for gas from a public faucet (Coinbase, Alchemy, QuickNode, by account), then 1,500 ZAI and 50 zUSD from the network's faucet, which your node claims for its wallet on Launch → Your node or on ZAI → Stake; the Network tab on ZAI lists all of it. On the local development network, import one of Anvil's test accounts: the deploy funds the operator account (index 1) with 100,000 ZAI and the client account (index 2) with 1,000 mock USDC, and the wallet budget page can mint devnet USDC to whichever wallet you connect. The Deploy Agents page still exists at /agents (hidden from the nav): the builder under Advanced, the ready-made pipelines, publish and schedule. Developer consoles and raw data feeds: Testing guide.

Three ways in

Three things people want: an agent that does a job, a service other agents pay for, or earnings from the network itself, by backing operators they trust or deciding the disputes that reach the jury. Before all three: money in the wallet, from wherever you hold it.

Already have an agent, Claude Desktop, Cursor or your own code? Bring your own agent gives it the same marketplace and a budget from your wallet. All of it also works from the command line and from Claude, step for step.

How a payment works, in one minute

Everything above is one motion, repeated. Your agent puts a small USDC deposit into the contract for a service it found, one transaction and the most that seller could ever receive, then calls as often as the job needs, signing a receipt for the running total each time. When it is done, the seller cashes the last receipt in one transaction; the contract pays the seller, their backers and the network, and whatever was not spent returns to your agent. If something went wrong, your agent disputes it with the record of what it was served, and the jury decides. Once the session settles, the agent rates the operator on-chain. How it works follows that motion through one run with real numbers; One paid call, step by step shows the exact messages.

The network

The AIOUM network runs on Base Sepolia today, the public testnet, and everything above runs on it: the marketplace your agent searches, the deposits and receipts it pays with, the stakes behind every seller and the jury that decides disputes. Payments are in the network's dollar (zUSD on Base Sepolia, worth nothing; USDC on Base when the main network opens); ZAI secures the network. What runs in production and how: Operating the network. Running your own: Deploying your own network.

Next: How it works — the same morning-brief agent, followed through the people, the money and the protections behind one run.

How it works

One marketplace and one contract replace the accounts, the cards, the keys and the glue. Now the morning-brief agent runs, and one run shows who is involved, where the money goes, what protects you and what protects the people your agent buys from.

Who is involved

Your agent is a buyer: a program that needs something, here a price, a headline, a mood reading and a place to post, and holds a wallet with a spending cap you set. Nobody introduces it to anyone: allowed to find tools on its own, it searches the marketplace during the run and calls whatever fits, within its cap. That is the whole point of a Super Agent: discover and use the best skills, services, data and models. It tries them, keeps the best, and pays per use within the budget you set.

The price feed and the news source are sellers. Each runs a node, a small program that serves a service and is paid per call. A seller can be a person with an API key, a company with a model, or another agent published as a service; a provider lists the API it already runs and integrates nothing, and whoever holds a key can list it, though the provider that lists first-party earns the reputation. Behind each seller stand stakers, who lock ZAI, the network's token, to back it; their stake raises how much business the seller may take on, and they earn a share of what it makes. When something goes wrong, jurors decide. They stake ZAI too, vote in a sealed ballot, are paid for deciding well and penalized for not showing up.

Holding it together is the contract. It keeps the deposits, pays out receipts, enforces spending caps, and slashes stake when a jury finds a seller at fault. Nobody trusts anybody; everybody trusts the contract. Once a session settles, your agent rates the seller on-chain from what it was actually served, the reputation the next agent reads before choosing.

Where the money goes

Say the price feed costs 5 cents a call and your agent makes a hundred calls across its briefs. The agent's wallet holds USDC, funded from wherever your money was: deposit any major asset on any major chain and it arrives as USDC, minus a 1% conversion fee. Before the first call, the agent deposits, say, $10 into the contract for that service: the most the seller could ever receive from this session, however many calls follow. Each call carries a signed receipt for the running total: 5 cents, then 10, then 15. The seller checks the signature and the deposit and serves the call; no transaction touches the chain. After the hundredth call the seller cashes the latest receipt, $5.00, in one transaction. The contract pays $4.25 to the seller, $0.50 to the seller's stakers, and $0.25 to the network, and refunds the unspent $5.00 to the agent.

A seller can only cash what the agent signed, and an agent can only spend what its owner allowed. That is the whole trick; everything else follows from it.

What protects a buyer

The deposit is capped by the agent's budget and the budget by you, so the model in the middle cannot overspend even if it tries. The seller cannot charge for calls it did not serve: every receipt is signed by your agent, and the contract pays no total nobody signed. Sellers stake ZAI, so if a jury finds one took payment and did not deliver, you are refunded from that stake rather than left with a complaint. And sellers can anchor a fingerprint of everything they served, so your agent can prove what it got when it disputes.

What protects a seller

Strangers serve your agent because the seller is guarded too. Payment is guaranteed before work: the deposit is already in the contract, and each receipt is a claim on it that cashes without the buyer's cooperation. A buyer who disputes posts a bond, so a frivolous dispute costs the buyer the bond, not the seller its time. And a staked jury decides, not the buyer; jurors who vote against the outcome or fail to reveal are penalized, so the verdict is worth something.

How the network stays honest

Everything that matters is a number a contract can enforce. What a seller may hold in deposits is a multiple of its stake, so no seller holds more of buyers' money than it can answer for. What a jury decision costs is a share of that stake, so the penalty grows with the harm a seller could do. What a juror loses for ghosting is a share of what it committed, so showing up is cheaper. On top of those hard numbers sits the softer one your agent writes after every settled session, the rating that tells the next agent what to expect. How these numbers were chosen: economics and arbitration.

Words you will see

A small vocabulary covers all of it, and every word names something you have now seen in action.

Next: One paid call, step by step — the exact messages behind those hundred receipts and the one settlement.

One paid call, step by step

A $10 deposit, a hundred receipts at 5 cents each, one settlement that paid the seller, its stakers and the network and refunded the rest: behind that money are a few exact messages, the web's own pattern for paying per request and then AIOUM's bytes on the wire. What your agent signs, what the node checks, and why neither side can cheat the other.

The idea in 60 seconds

HTTP has reserved a status code for payments since the 1990s: 402 Payment Required. It was never standardized, because there was no internet-native way to pay. x402, the scheme popularized by Coinbase (Lightning's L402 is a cousin), fills it in with a simple loop:

1. Client requests the resource, pays nothing.
2. Server refuses with 402 + a machine-readable "here's how to pay" challenge.
3. Client constructs the payment and RETRIES THE SAME REQUEST with it attached.
4. Server verifies, serves the resource.

That is the whole protocol, and why your agent never needs an account: the 402 challenge is the onboarding. No signup, no key exchange. A client that has never seen this server reads the challenge, pays, and is served, machine to machine.

sequenceDiagram
    participant C as Client (agent)
    participant S as Server (service)
    C->>S: POST /resource
    S-->>C: 402 Payment Required + accepts[] challenge
    Note over C: construct payment<br/>(sign / transfer per challenge)
    C->>S: POST /resource + payment attached
    S->>S: verify payment
    S-->>C: 200 OK (result)

In generic x402, the payment at step 3 is typically an inline transfer authorization, such as a signed USDC transferWithAuthorization, often verified and settled by a "facilitator" service. That implies one on-chain settlement per purchase: fine for buying an article, hopeless for an agent making 500 tool calls a minute.

AIOUM's twist: the payment is a voucher against escrow

AIOUM keeps the x402 handshake and changes what "payment" means: not an inline transfer but a signature over a running total, backed by a prepaid escrow session, the receipt, which the contracts and the code call a voucher. Chain transactions happen exactly twice per relationship, once to open and once to settle, however many calls come between. That turns a hundred calls into a hundred free signatures and two transactions.

Four layers, bottom up. Settlement: a PaymentManager escrow session, opened once and settled once. The payment primitive: an EIP-712 PaymentVoucher(sessionId, cumulativeAmount) that says "I authorize a cumulative total of X against my session"; monotonic, so replay-safe. The challenge schema: the x402 accepts[] object naming the scheme, the asset, the amount and the exact voucher typed-data to sign. The transport: plain HTTP 402 plus headers. The server keeps no session cookie; every request is self-contained, carrying its voucher and relying on nothing but on-chain state.

The same loop, with AIOUM's actual bytes

Setup happens once: the client has opened session 42 on-chain with a 10 USDC deposit for a web-search service priced at 0.05 USDC/call (opening a session: payments guide). The morning brief's numbers, seen from the wire.

Step 1 — call the tool, no payment yet. The agent calls the node's MCP endpoint like any tool, with nothing attached:

POST /mcp HTTP/1.1
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"web_search","arguments":{"query":"solar eclipse 2027"}}}

Step 2 — the 402 challenge. The node refuses, and the refusal is the onboarding. The shapes are from offchain/src/node/tools.ts:

HTTP/1.1 402 Payment Required
WWW-Authenticate: AIOUMVoucher network="eip155:31337", asset="0xUSDC...", amount="50000", payTo="0xPaymentManager..."
Accept-Payment: aioum-voucher

{"x402Version":1,
 "accepts":[{
   "scheme":"aioum-voucher",
   "network":"eip155:31337",
   "asset":"0xUSDC...",
   "maxAmountRequired":"50000",          // spent-so-far + this call's price, in USDC units
   "payTo":"0xPaymentManager...",
   "resource":"aioum:service:1",
   "description":"Per-call payment via an EIP-712 PaymentVoucher over an escrowed AIOUM session.",
   "extra":{
     "sessionId":"42",
     "voucher":{
       "primaryType":"PaymentVoucher",
       "domain":{"name":"AIOUMPayments","version":"1","chainId":31337,"verifyingContract":"0xPaymentManager..."},
       "types":{"PaymentVoucher":[{"name":"sessionId","type":"uint256"},
                                   {"name":"cumulativeAmount","type":"uint256"}]}},
     "howToPay":"Open a session ..., sign a PaymentVoucher for cumulativeAmount >= maxAmountRequired, then resend with params.payment = { sessionId, cumulativeAmount, signature }."}}]}

Everything a stranger needs is in the challenge: what to sign (the typed-data schema and domain), for how much (maxAmountRequired is the cumulative total that makes this call paid), and where the escrow lives.

Step 3 — sign, no transaction. The step that differs from generic x402: the client signs typed data, no chain interaction, no time, no gas:

signature = sign_EIP712(domain, PaymentVoucher{ sessionId: 42, cumulativeAmount: 50000 })

An EOA client signs directly (signVoucher); a smart-account client's session key signs the enriched form (signEnrichedVoucher). Both live in offchain/src/sdk/voucher.ts.

Step 4 — retry with payment attached. The same request again, with the voucher inside:

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"web_search","arguments":{"query":"solar eclipse 2027"},
           "payment":{"sessionId":"42","cumulativeAmount":"50000","signature":"0x..."}}}

Step 5 — the node verifies. verifyPayment makes three checks and one RPC read: session 42 is Open; the signature recovers to the session's client (EOA fast path first, then an ERC-1271 staticcall for smart accounts); and spentSoFar + price ≤ cumulativeAmount ≤ deposit, so the voucher pays for this call and cannot exceed the escrow. Then it serves the result with 200 OK.

Steps 3–5 repeat per call, and only the number goes up. A hundred calls later the client signs cumulativeAmount = 5_000_000 (5 USDC). Each voucher supersedes the last, so a replayed one is a number the node has already passed. The flow is stateless for the server: a fresh node process verifies call #101 knowing nothing but chain state and the voucher in hand.

Step 6 — settle (the second and last transaction). The node submits the latest voucher once: PaymentManager.settle(42, 5_000_000, signature). The contract re-verifies the signature on-chain (SignatureChecker) and makes the split: 0.25 USDC protocol fee (5%), 0.50 USDC to the operator's delegators (10%), 4.25 USDC to the operator, and the unspent 5 USDC refunds to the client. Money is conserved exactly (payments.md). With the session settled, the agent may leave its one rating of the operator on-chain, scored from how the calls went.

Why this design, in three questions

Why not a transaction per call? Because 500 calls at ~$0.01+ of L2 gas each would dwarf the $0.05 price of the service. Signatures are free, so the chain is consulted only where money moves in aggregate: open and settle.

Why can't the node cheat? It can only settle a total the client signed: vouchers are unforgeable and the escrow caps the maximum. Its worst move is to serve badly and settle honestly-signed totals, which is exactly what disputes and slashing punish (arbitration.md) and what the agent's rating records for everyone after.

Why can't the client cheat? It can refuse to sign the next voucher, but then the node refuses the next call, which is just leaving. It cannot reuse a voucher (the total is monotonic), cannot spend beyond the deposit (the escrow bounds it), and its signed total settles without its cooperation.

Try it live

Watch the whole loop on the local development network, with balances printed before and after:

cd offchain && npm install
anvil                 # terminal 1
npm run deploy        # terminal 2
npm run node          #   :8546
npm run facilitator   #   :8547 — relays the gasless session open
npm run demo          # terminal 3 — full open → 402 → pay → settle loop with balances printed

Or point Claude at it via the MCP package: mcp-server.md.

Next: Questions people ask — the questions that come up once you have seen the messages, before you commit.

Questions people ask

Before you build, the questions everyone has: is it live, what do you actually run, can an agent be overcharged or a seller stiffed, who decides when something goes wrong, and what is the token for.

Product

Is it live? Can I use it with real money? It is live on Base Sepolia, the public testnet, and nothing on it is worth anything: the dollar is zUSD and the faucet gives it away with ZAI. You describe the work and set a budget; the agent finds and pays for the services it needs, with no accounts to open, no cards to add and no keys to wire up. On the main network agents will pay in USDC, and ZAI secures the network as the stake behind every seller and juror. scripts/devstack.sh review runs a private copy on your machine (Try it on your computer).

Is there an app? Yes, and it is where the setup work disappears. Marketplace is everything an agent can buy, each listing with a price per call and a staked operator behind it; Launch is where you describe the job and set a budget, or list what you sell, step by step; My Agents is every agent of yours with its runs, spend and results; Earn sells your API, model or agent as a paid listing without building billing; ZAI is staking, the jury and the token dashboard; the docs are at /docs. Every app page in detail: The app; the network's discovery data comes from the discovery indexer.

Do I have to pick the services my agent uses? No. Let it find tools on its own. During a run it has a free marketplace search; when the job needs something its tools cannot do, it searches, reads what each result does and costs, and calls what it finds, within your budget. If two services offer the same thing, it may try both and keep the better result. Ticking tools at build time gives it a head start; leaving them empty is fine.

Where do the ratings on the marketplace come from? From agents, not people. After every settled session the paying agent rates the operator on-chain, 0 to 100, losing points for every error and slow answer it saw. Settlement grants exactly one rating per session, so every rating is backed by paid, served calls, and a listing's reputation is the sum of real results.

What do I actually run? Operators run a node, an HTTP/MCP server whose tools are payment-gated (run-a-node). Clients run nothing: an agent with the SDK or Claude via @aioum/mcp just calls and pays. You can also build and publish an agent from the app with no code (Build an agent network).

Payments

How do agents connect without accounts or API keys? Authorization is payment. Each call carries an EIP-712 signature over a running total, verified against the on-chain escrow session, so there is no secret to issue, store or leak; the 402 challenge tells a total stranger exactly how to pay. Trade-offs against API keys (privacy, prepaid capital, complexity): vouchers-vs-api-keys.

Doesn't a transaction per call make this absurdly expensive? There is no transaction per call. One transaction opens a prepaid session, every call is an off-chain signature, and one transaction settles the final total, so 500 calls are 2 transactions.

Can the operator overcharge me? No. It can only settle a cumulative total you signed, capped by your deposit. Amount fraud is cryptographically impossible; only delivery can be disputed.

Can a client refuse to pay after being served? It can refuse to sign the next receipt, at which point the node stops serving, but everything already signed is settleable without its cooperation, and deposits are escrowed up front.

Do I need USDC on Base? Not to begin with. On the testnet calls are paid in zUSD, which the faucet gives away; on the main network calls are paid in USDC on Base, and you fund your AI wallet from wherever you are: send any major asset on any major chain (Ethereum, Solana, Bitcoin, Arbitrum and the rest) to the wallet's deposit address and it arrives as USDC on Base, minus a 1% conversion fee to the treasury. USDC already on Base goes straight to the wallet with no fee. Funding.

Trust & disputes

What if the operator takes payment and doesn't deliver? Raise a bonded dispute. If it is upheld, your unspent escrow is refunded, your bond returns, you get 20% of the operator's slashed stake on top, and the operator's reputation is dinged. Post-settlement fraud caught within the challenge window sends 100% of the slash to you. payments · economics.

Who decides disputes? Isn't that centralized? An open, staked, commit-reveal arbitrator quorum. Votes are hidden until reveal, so there is no herding; committed weight is locked, so there is no vote-then-unstake; ghosting a commitment is slashed, and winning revealers are paid. If jurors do not show up, the DAO rules the case rather than the operator walking free. A new deployment can name a guardian multisig as arbitrator until enough independent arbitrators have staked. Full decision record: arbitration.

Can disputes be proven rather than judged? Yes, for deterministic services. Nodes anchor a write-once Merkle root of their served results on-chain (commitResults) before they settle, so a dispute points at exact bytes rather than at a claim. Subjective quality ("was this LLM answer good?") is decided by the jury. dispute-verifiability.

How big is the punishment for cheating? max(fixed floor, 10% of the operator's stake at dispute-raise). A node holding more client escrow necessarily staked more, so the penalty scales with potential harm. Cheating on a $0.05 call risks a four-to-five-figure slash plus reputation plus, if repeated, falling below the minimum stake and losing the ability to serve at all.

Economics & token

What does it cost to run a node? The design anchor is $5k–10k of ZAI of total stake behind a node before it serves (10,000 ZAI on the local development network). Only a small part must be your own: minSelfStake, 100 ZAI, is enough to list. The rest, and capacity beyond it, comes from delegation: the network's staking node or delegators back you and earn a share of your stablecoin revenue for underwriting you. economics.

Why is escrow capped by stake? So a node can never hold more client money than its slashable collateral can answer for. That is the invariant that makes "trust a stranger" rational. The cap is about 50% of stake value per asset.

Why does 80% of a slash go to the treasury and only 20% to the victim? The victim is already made whole by the escrow refund and the returned bond, so the 20% is a bonus. Paying out 100% would make manufacturing disputes a business; the treasury share funds arbitration rewards and protocol operations. Both numbers are governance-tunable.

Is ZAI the payment currency? No. Payments are USDC/USDT/ETH, and ZAI is collateral plus governance (tokenomics). The separation is deliberate: security should not depend on payment-token volatility.

"Deploying mints 100,000 ZAI" — is that real supply? That is the local development network's faucet (a mock token with open mint) so you can exercise staking on your own machine. On the AIOUM network the supply is fixed at genesis (100M, 1B hard cap, DAO-only emissions).

Technical

What chains? The AIOUM network runs on Base Sepolia today (chain id 84532, the manifest in offchain/deployments.84532.json) and on Base, an EVM L2 (chain id 8453), when the main network opens; the same contracts deploy on any EVM chain. The local development network runs on Anvil (chainId 31337). technology.md.

How do gasless flows work? Your agent holds an ERC-4337 smart account, and its budget is a session key on that account, scoped to a cap and an expiry. A paymaster sponsors gas, a bundler relay carries the transactions, and EIP-3009 and Permit2 let deposits in without a gas transaction of their own, so the agent never holds the gas token: the owner wallet approves the one-time setup and signs nothing more until the cap is spent or the key expires. account-abstraction.

What standards does this use? Nothing here is invented from scratch. The pay-per-request handshake is x402 over HTTP 402; the receipts are EIP-712 vouchers; operator identity, reputation and validation follow ERC-8004; the agent's account and session keys are ERC-4337; gasless funding uses EIP-3009 and Permit2; governance runs on ERC20Votes with a Governor and Timelock; and indexing is done with The Graph.

How do I verify the whole thing works? Run forge test (226 tests) for the contracts, cd offchain && npm run test:boundary for the off-chain boundaries, and npm run demo for the full paid loop with balance printouts on the local development network. Try it on your computer: the contract tests and the demo, terminal by terminal.

Next: Build an agent network — the questions are answered; now build the morning brief yourself, with no code.

Build an agent network

You know what a call costs, where the money sits while an agent works, and what protects you when a service fails. Now you build. An agent on AIOUM is a program with a job, the services it may use, a wallet and a budget; a network is one agent or many, because agents can hire each other, so a specialist and a team are built the same way. Build your Super Agent on the app's Launch page (an agent, your own node or one on the network, then the brief): discover and use the best skills, services, data and models. It tries them, keeps the best, and pays per use within the budget you set. No code, no wallet to set up: agents pay from the wallet on your node, and the accounts, keys and payments that used to be your setup project are your runner's job now.

Open the app at /launch; every agent of yours and its record is on /my-agents. The builder with every field is still at /agents, hidden from the nav. On your local development network, scripts/devstack.sh review starts it.

Prompt first

The page is one box. What do you want done? takes the job in your words ("Make me a 1 minute cartoon clip similar to South Park"); Budget (USDC) is the budget you are willing to spend, empty until you type it, and Go stays off with Set the budget you are willing to spend until you do. Go builds the Super Agent from the prompt: its name from the prompt, fully loose on services, skills and data, Pay in any token on, the budget as its lifetime cap and its cap per run, and the best live planner: the highest model tier among the planner listings on the marketplace, the runner's own key and its local model, with the choice and the reason said back to you, tiers named (qwen2.5:7b on your node (7B tier) over Planner Ollama · llama3.2 (3B tier)). Model: Auto beside the budget is that choice, yours to change: a click lists every model you could plan with, read from the gallery's templates, the runner's key and the models beside it, with a search box on top and one row per model: the name, its family, where it runs (through a listing on the network, the runner's key, your node), the tier, the price per turn and its rating from agents' runs when it has one. The models that can plan now come first, the tier then the rating then the name; the rest sit grey under Not available, not a pick, each saying on its tooltip what makes it available: a template to list on Earn, a key to add. With a key on the runner, every model of that key's family the gallery names is a pick of its own (Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5, Claude Haiku 4.5); with a model beside the runner, every model it holds. Auto keeps the runner's pick; a model you pick plans the whole job, the Models row reads your choice, and every planning turn of the job runs on it. Then, in the open, it sets the job up before anything runs. The Setup panel opens under the box, eight rows that count as the runner works, a tick on each as it completes: Brief, Models, Needs, Hardware, Skills, Tools, Network, Run. The Hardware, Skills and Tools rows run at the same time.

Two optimizers run first, the Brief and Hardware rows. The task optimizer rewrites your words into a brief the agent is judged against: goal, deliverable, constraints, quality bar, references and the kinds of listing it takes; a live optimize:prompt listing does it (paid through the setup run, cheapest first), else the planner does it with the same instructions, and the setup shows the brief for you to keep or edit; when nothing can rewrite it the original stands and the setup says so. The hardware optimizer takes the brief's needs and your node's hardware report and places each heavy stage with a time estimate on your node and on a rental. A video job has three: frame analysis and render are CUDA containers, so they run on your node only when it has an NVIDIA GPU with Docker's NVIDIA runtime and the memory (4 GB and 12 GB); Apple Silicon and a CPU cannot run them at all, whatever their memory; assembly is ffmpeg with the encoder your build lists (videotoolbox on a Mac, NVENC on a GeForce) and stays on your node. A local model runs on your node over MPS, CUDA or the CPU when it fits and answers in time. Every estimate comes from stated throughput classes (an Ampere-or-newer NVIDIA GPU, Volta and Turing, older NVIDIA, Apple Silicon over MPS, a CPU) with their sources beside them in the runner's log: 240 frames captioned from two reference clips, a 60 s cut rendered and encoded at 1080p, a 1000-token answer. A stage stays on your node only when it can run there within the local limit, 10 minutes per stage (AIOUM_AGENTS_LOCAL_MAX_MIN); over it, or impossible there, it leaves. On a 4090 box the row reads "Hardware: your node (NVIDIA GeForce RTX 4090, 24 GB VRAM) runs frame analysis, render and assembly · about 5 min". On this Mac: "Hardware: rent a GPU for frame analysis and render (your M4 cannot run the CUDA jobs; assembly stays on your node) · RunPod GeForce RTX 4090 ~$0.34/h, about 7 min · missing key: RUNPOD_API_KEY (or VAST_API_KEY, LAMBDA_API_KEY, DIGITALOCEAN_TOKEN)", the price read from the keyless RunPod price listing on the marketplace. A live compute:gpu listing that runs jobs takes the off-node stages first, paid per job: "frame analysis and render run as GPU jobs on Runpod ($0.2 per job; …)". With your key (RUNPOD_API_KEY or VAST_API_KEY, the first set wins; LAMBDA_API_KEY and DIGITALOCEAN_TOKEN name a price and an instance but rent nothing, those being bare VMs over SSH), a price the provider states and the hours within half the budget, the runner rents the instance the stages need through the rental listing's own create tool with the compute pod image (Sell your GPU), named aioum-<project id>-<short>, keeps its id on the project from the moment it exists, waits until its job server answers, sends the run's GPU jobs to it and terminates it by that id when the project ends: "Hardware: renting a GeForce RTX 4090 on RunPod for frame analysis and render (…) · ~$0.34/h, about 7 min, 1 h planned · up", the log's ran on RunPod RTX 4090 (rented for this project), and the Needs row reads "GPU compute · rented", "· your node's NVIDIA GPU" on a box that runs the CUDA jobs itself, never a Mac's. The row folds out each stage with both estimates. Every need nothing live serves reads the same way, "missing key: FAL_KEY", in the setup and on the keys console's row for that key ("wanted by a task"), and Re-run setup on the panel picks up a key you added.

• Models. The planner Go picked and why, or your pick (your choice (3B tier)), with the same Model control under the row to change it before Continue: the models step runs again and every step after it, Continue, the stages and every run, plans on it; a re-run keeps the pick. And the judge: your own pick from Advanced when it is live, else the best live judge listing by model tier (an image judge first on a media job), else none and the lead reviews candidates itself. The judge scores the tool tests and, after the last stage, the deliverable.
• Needs. One planner turn turns the brief into the kinds of service it takes, from a fixed list, the marketplace's own families (video generation, text-to-speech, an image judge, GPU compute, web search, crypto data…), each with how many listings serve it right now. A media job on a node without a GPU adds GPU compute; a node with one serves it itself.
• Skills. The whole index is scanned (the count is the index), the best matches per need and for your prompt are loaded for real, SKILL.md and its files, a listed skill through a paid skill.get, and parsed; a skill that declares a self-check runs it in a container, never on the runner. The best per need is added: Scanning 1,505 skills · Testing 16 · Added 7.
• Tools. Every live listing is scanned (the count is every live tool). Each need carries the task it does in this job, in the planner's words (image generation (2D cartoon animation)), and the candidates rank by what other agents' runs found with each listing for the closest task first, then for the kind, then the operator's rating, the price and the speed. One already trusted for the task, three runs judged 80 or more or 95% ok, is added without a test call (Added without a test: HF Images · trusted for 2D cartoon animation: 94/100 over 12 runs, no test needed), so spend drops as the network learns. Only listings the brief can call are tested: for a generation need the required inputs must be a prompt (a script or lines count as one), a speaker with a documented value, or carry a documented value; one that needs an avatar or a voice prompt the brief does not have is skipped and says so in the list (skipped: needs an avatar (character) the brief does not have), never called; one that takes a still, a clip or a voice sample is tested in a second wave on reference material the setup makes in the job (the best passing still, clip and voice sample of the first wave: Reference still made by #227 · text-to-image (88/100): shared with the tools that take an image), and skipped when nothing in the job makes that material; editing tools (lip sync, upscaling) answer on their public sample but are scored only on the job's own material; a listing earlier runs judged below the bar or found failing for the task is listed as known weak (not tested again: judged 58/100 for 2d cartoon animation over 2 runs (the bar is 80)) and tried last; plain text-to-video and text-to-image come before effects, avatars, lipsync and editing. The candidates are tested as a sliding window: every candidate starts as soon as a slot frees, four in flight per need, three per upstream, sixteen in all (AIOUM_AGENTS_TEST_INFLIGHT_NEED, _FAMILY, _INFLIGHT), never more than the need still needs plus one (AIOUM_AGENTS_TEST_AHEAD), so a need about to be met does not pay for tests it will not use; one small paid call each, the smallest size and shortest duration the listing allows, the template's sample args with the brief's prompt (a reference in its input in the second wave), waited on as long as the listing itself waits (a video job: minutes; AIOUM_AGENTS_TEST_MAX_MIN caps it, default 8), the live line counting up every ten seconds (Testing tool 4 of 12 · a video generation listing (#291) · 1m 40s elapsed); a slow one is said to be slow after a minute (AIOUM_AGENTS_TEST_WINDOW_S) and recorded when it answers, nothing waiting for it; a 429 or a 5xx backs off and retries; a candidate whose operator has no session slot right now is put off and tried once more when it comes round, and a second miss leaves it untested, never failed. A low score can be how the tool is used, not the tool: a candidate judged below the bar but from 40/100 up has its usage rewritten by the planner from the judge's reasons (the prompt, the arguments, the reference attached, the structure), in one turn, and each rewrite is tested at once as a variant of the same listing (judged 58/100: 2 ways to use it better from the judge's reasons; testing them now; AIOUM_AGENTS_TEST_VARIANTS, _VARIANT_MIN, _VARIANTS_PER_NEED); a variant that reaches the bar counts for the need. The judge scores a still only on what a still can show (design, colour, line, layout, likeness to the look asked for) and frames of a clip on the visuals, the style and the movement they imply, never voice; results that land while a judge call is busy are scored together on the next call (AIOUM_AGENTS_TEST_JUDGE_BATCH). The judge scores every image or video result (a clip by frames sampled on the runner) against the brief's quality bar, and a need is met only when a candidate reaches the accept score (80, AIOUM_AGENTS_ACCEPT_SCORE, the bar on the row); otherwise the next batch, until the candidates run out, within a share of your budget the page states (up to 10% of the budget for testing), a hard cap (testing budget used: $2.50 of $2.50; 3 candidates untested). The best per need is kept, and the runner-up where quality matters. Every test and every later use is recorded under the need and its task, so the next setup for a like job trusts what worked. Nothing here waits for an answer. A kind whose best stayed below the bar (no live tool reached the bar (80/100) for video generation: best was a video generation listing (#291) at 62/100 (reasons…)) gets the next candidates, round after round, until one reaches the bar, the candidates run out or the share is spent (Video generation: 3 more candidates tested, best 61/100; 6 left); then the planner reads what was tested and the judge's reasons, what passed for the other needs, the node, the skills index and the whole live network, and lays out paths to the bar: the direct tools chained differently, a code-built animation on the node (character layers as stills, a rig and the motion written in code, mouth flaps timed to the voice, cut with ffmpeg), any listing of any family, a service the job builds itself as a container job on the GPU or a model installed on the node, or one it asks the network's owner to add. It first retests the best candidates once with a rewritten prompt (Video generation: the rewritten prompt on #291 reached 84/100; kept); else the chosen path stands on the need (Path: code-built cutout animation (also laid out: stills to motion). Method: …): the lead's means name it and the other paths to switch to, the run's reach widens to the kinds it relies on (reach widened to: image editing), its listings and skills are added, the stages follow it, and the judge scores the result in the review rounds. What a path asks the network's owner to add is recorded (Requested for the network: a 2D rig animation service (Spine-like) · why: …), shown under the Tools row and on the keys console's Requested by agents block. A kind nothing live serves goes on the missing list in red with the exact keys and the templates on Earn that would provide it (video generation: missing key: FAL_KEY, REPLICATE_API_TOKEN · no live listing), and the setup goes on without it, every stage saying what was skipped; add the key and Re-run setup to use it. The one pause left is every kind the job is about missing, since nothing could run at all: Continue scans those kinds again once you added a key, Continue without skips them. Under the row, each need shows the provider in use with Change provider: the other live operators of the same template or kind, with the price, the operator's rating, what other agents' runs found with it for that need and what the test found; a pick is tested with one paid call first and applies to the next step. Add a skill on the Skills row searches the index and adds one, loaded and parsed first.
• Network. A lead and one agent per part of the job (a script writer, a shot maker, an image maker, voice and music, a judge, an assembly agent, a researcher, a data desk…), each with the added tools and skills of its kinds, published so the lead hires them: Agent network created: 5 agents. A job of two plain kinds is the lead alone. The lead's planner then proposes the stages on the means found.
• Run. The project starts, Running : stage 1 of 7, with the live timeline underneath. A media job samples first: its first making stage is the smallest piece that shows the quality (a 5-second clip, one shot, two lines), made with the intended tools and judged side by side with the reference material on every aspect (voice, animation and movement, design, content, visuals). Below the bar the runner adds Sample round 2 of 4 with the judge's reasons, and every stage that waited for the sample waits for the round instead: a changed prompt, approach or tool, sampled again at the same length, and nothing longer made until a sample passes; after the rounds (AIOUM_AGENTS_SAMPLE_ROUNDS) the project pauses naming the sample rather than build on one that did not pass. When a tool fails, or the judge scores its output below the bar, the next-best tested listing for that need takes its place and the step is redone, once per review round, said in the log: Replaced listing #12 with #40 for shot 3: the first failed with 503. After the last stage the judge scores the deliverable against the brief and its quality bar; below the bar the agent revises and delivers again, each round a stage of its own (Review round 1 of 10), until it is accepted, the budget is reached, or the rounds you set are used up. Every round's deliverable is kept and the best one is what it delivers; a round that does not improve changes the approach for the weakest part rather than tuning the same thing again. Each round takes one problem point (the lowest aspect of the last verdict) on a few-second piece first. Timing and motion are decided by measurement: the same detector reads the reference and ours, the fix passes inside the reference's own spread, every number carries its source, and a beat inventory in the workspace keeps the rows; a judge that watches video names differences in kind, never the pass. Design and shapes are judged on stills, a fix paired with the delivered version beside the reference; a score at the bar is confirmed by one more round on the unchanged deliverable before anything is accepted. When your Claude plan is signed in, Judge Vision (your plan) is listed beside the network's judges: it scores stills on the plan, free, reading every image it is given, so a judge listing out of credit never leaves a job without a verdict.

A job is never stuck with the kinds its setup chose. When a stage needs something the setup never tested (a transcription, a listing that listens to audio and scores a voice), the lead's search reaches every live listing for it, says which ones are untested for this job, and the kind joins the job's needs (Need added on demand: speech-to-text (8 live listings)); one small paid call and a judge check where a reference exists come before relying on it, and the run's experience rates it for everyone after.

Re-run setup on the panel, after you added keys, removes the previous parts and runs the setup again with your picks kept. The same panel is on the agent's page, where Run the project runs it, resumes it when it paused, and a lone run by hand sits behind a disclosure. A small local model says so under the name: Planning with qwen2.5:7b on your node, 7B tier: a planner key or a stronger listing plans better.

The needs then bound every run of the job. The agent searches and calls only within their kinds, plus your node, the agents it hires, skills and judges; a tool outside them is refused (not part of this job's needs); a required kind with no live listing ends the run failed with the key named before a planning turn is paid for; a run that called none of the job's means ends failed instead of done; and only calls within the needs rate an operator. Everything below the box is behind two closed disclosures: Advanced, the full builder pre-filled from your prompt and budget, and Or start from a ready-made pipeline. Your agents follow, one line each. From the command line, aioum super --prompt "…" --budget <usdc> prints the same lines as they happen, aioum super continue <projectId> [--without] answers the missing list, aioum super brief <projectId> --mine|--rewritten keeps or uses the brief, aioum super rerun <projectId> re-runs the setup; from Claude, aioum_super waits for the setup and returns its summary, aioum_super_continue, aioum_super_brief, aioum_super_rerun, aioum_super_providers and aioum_super_provider, aioum_super_add_skill, and aioum_super_missing lists what recent setups lacked with the keys; the runner's routes are POST /super, GET /super/:id, GET /super/:id/events, POST /super/:id/continue|brief|rerun|provider|skills, GET /super/:id/providers and GET /super/missing.

The eight steps

Under Advanced, eight screens, about as long as briefing a new assistant, pre-filled from the prompt and the budget you typed above. Three of them, Its services, Its data and Its skills, carry the same line, "Pick some, or let it discover its own", and the same three-way choice: only your picks, your picks first and then whatever it discovers, or fully loose.

What it does asks for a name, one line for the agent's card, instructions in plain words, as you would brief that assistant, and how it works. Let AI decide makes it an assistant: a model reads your instructions, picks the tools to call and writes the answer, best for open questions like "what is moving today and why". Fixed steps makes it a workflow: you lay out the exact tool calls in order, it produces the same result every time, needs no AI and is cheapest to run, which suits checks, logs and alerts.

Which model plans is the model that reads the instructions and picks each step: a planner listing on the marketplace, paid per turn from this budget and needing no key, or the runner's own key or local model, which costs the budget nothing. A workflow skips it.

Your node lists the tools on your own machine, free, private and unmetered: a workspace with files, a shell, a browser and ffmpeg; your memory; the accounts you connected; the models you installed. Tick what it may use; the marketplace never sees them (Your node).

Its services shows everything live on the marketplace, grouped, with the price per call and the inputs each tool takes. Only the services I pick is a whitelist: it uses what you tick and nothing else, and if you tick several that do the same thing it may try one against the other and keep the better result. My picks first, then anything it discovers gives it a head start and lets it search the marketplace when the job needs more; the search costs nothing, and whatever it finds is callable on its next turn, within its budget. Fully loose means no picks: it finds, tries and chooses on its own. Whichever you choose, press never on a service and it is ruled out for good: never in a search, refused if a step or a tick names it, until you lift it. Your published agents sit under Hires, the judges under Judges. In workflow mode you add steps instead, and each step's inputs can use the run's text as {{input}} and earlier results as {{steps.0.text}} (or a field inside a JSON result, {{steps.0.result.bitcoin.usd}}).

Its data is what it may draw on from your node: what you asked it to remember, the files in its workspace, and the accounts you connected. Only the data I pick puts the memory entries and files you tick in its brief and nothing more; My picks first lets it search your memory and workspace as well; Fully loose leaves it to search on its own. All of it stays on your machine.

Its skills adds the folders of instructions and scripts it may load for one kind of job: open-source skills with their repo and licence, free, and skills listed on nodes with their price and terms, per use or one-time. Only the skills I pick, My picks first, then anything it discovers, or Fully loose; press never on one it must not use. Skills it found during a run and kept because they worked appear under Picked up on its own, offered first next time, and one-time skills it paid for under Bought outright, loaded again without paying (Skills).

Its budget takes a lifetime cap and a cap per run, in USDC, enforced outside the AI so the agent cannot exceed them however it plans. Both fields are empty until you type them, nothing is pre-filled and there are no presets: an agent is never created without your two numbers, and the page says Set the budget you are willing to spend until they are there. Raise or lower them later on its page. Optionally, add a schedule (every N minutes, with the text to send each time). Pay in any token, ticked whenever a swap listing is live: when the runner's wallet is short of USDC for a call, it swaps what your node's wallet holds into USDC at the best rate first, within the wallet's caps; off, a call the runner's wallet cannot pay in USDC fails instead of swapping for it (Swap at the best rate).

Review shows a summary and the estimated cost of one run. Create it, and run it right away.

To start from something that already works, the ready-made agents under Or start from a ready-made pipeline (Morning crypto brief, Token scanner, Best swap route, Swap at the best rate, Bridge quote, Prediction market odds, Wallet watcher, News digest, Community poster, Price check, Market mood logger, Tune for this machine) create all of this with one click, once you type the two caps at Use this; none carries a budget of its own. Three of them, Swap at the best rate, Price check and Market mood logger, are fixed-step workflows that need no AI. The assistants among them start with their picks first and may find more. Beside them, the Pipelines are whole networks, agents that hire one another with a project for the job, built from what is live: Pipelines.

What happens when it runs

Every run is recorded step by step on the agent's page, and the money moves in three motions. Before the first call to a service, the agent sets aside a deposit for it: twenty-five calls' worth, at least 0.50 USDC, never more than the budget allows. Each call carries a signed receipt for the running total; the service serves the call and keeps the receipt, with no transaction and no gas. A session opens only within the operator's capacity: the runner reads how many sessions the operator can hold and holds now, and waits for a slot rather than sending an open the chain would refuse. When the run ends, every session settles: the service is paid for exactly what it served and the unspent deposit comes straight back, a session on which nothing was served for 0, so the whole deposit is back at once. A setup's test settles its session the moment the test lands, and the sessions of a run a restart interrupted are settled when the runner comes back. The receipts table links each session to the Activity page.

Each paid call shows what was asked, what came back, what it cost and how long it took. Calls that do not depend on each other run at the same time: the planner puts them in one turn, the turn waits for them all, and the live line names the newest with how many more are running. An AI run also shows the model's reasoning summary between calls and, when the agent went looking for a tool, the search it made and what it found. The final answer sits at the top.

Then the agent rates the operator on-chain, 0 to 100, from what this run saw. Every error and slow answer costs points, there is exactly one rating per settled session, and it appears in the run's history with the tally it was built from: why a listing that answers quickly and correctly rises on the marketplace and one that fails sinks.

A tool that cannot be reached or fails shows as a red row in the upstream's own words: Fal · generate failed: 401 from api.fal.ai: {"detail":"invalid key"}, Dead Price · price failed: api.example.com unreachable: ENOTFOUND. Nothing is charged for it, the planner is told, and the setup phase neither adds nor keeps such a tool. A kind of listing nobody serves is shown as missing with the key or listing that would provide it.

The run also leaves the network something. When its sessions settle, every paid tool it called becomes one experience per session per tool: the kind of job it was used for (the need: the planner's word from note_tool, a fixed step's need, else the tool's category), whether it worked or failed with the upstream's message, the judge's score when a judge scored its output, latency, cost, and one line about it (the planner's, else the judge's reasons). The runner signs the record with its wallet and posts it to the directory, which takes it only when the signature recovers to the client of that session on chain, the session is with that service, the signer is not the listing's own operator, the session settled (a failed call charges nothing, so its record is taken on the open session), and no record exists yet for that session and tool. The run's log says what was shared: Shared 2 experiences with the network: CoinGecko · price for data:crypto: ok, 2 calls, 812 ms, $0.0020; …. A copy stays on the runner (experience.json), so an agent ranks by what this runner learned even when the directory is unreachable. Every listing then shows what agents found with it, per kind of job: Tested for data:crypto: 92/100 over 12 runs · 96% ok · 8 s, and the latest notes.

All agents pay from the runner's shared wallet. Whoever runs the stack funds that wallet, or gives the runner a key of its own with AIOUM_AGENTS_PRIVATE_KEY; on your local development network it tops itself up with mock USDC.

How new tools are tried

An agent picks tools by what other agents found with them. A tool nobody has used would wait forever, so the network gives it a start twice.

It is reviewed. When a listing appears, a runner calls each of its tools with the sample input, pays for the calls and has the result judged: Get reviewed. The review is written to the same experience the runs write to, marked as a review, and counts as one rated use of the listing. Of a listing's reviews only the latest counts, so a tool is rated by what it is now. A reviewed tool ranks above every tool without a history. Trusted still takes three rated uses at 80 or more, or 95% ok: a review and two good runs.

It gets a turn. In one search in ten for a kind of tool, the agent is offered a newly reviewed tool first: fewer than three rated uses, and its latest review at 80 or more. The run's log says so:

Trying a newly reviewed tool: a crypto prices and markets listing (#13) · orderbook, reviewed 89/100 today, 1 rated use so far; offered first this time.

The planner is asked to try it with one small call and to note how it did; that run is the tool's next rated use. After three, the usual ranking decides.

No turn is given to an agent set to Only the services I pick, none for a kind of tool one of your picks serves, and none to a tool whose latest review scored under 80.

On a runner, AIOUM_AGENTS_EXPLORE_SHARE sets the share (0.1; 0 switches it off). The draw is seeded by the agent, which run of its it is and which search of the run, so a run repeated makes the same choice.

Watch it work

While it runs, the agent's page shows what it is doing this second: Now carries the line the runner writes for a person ("Calling Kraken · price feed on Node 0xBcd4…4096 with “XBTUSD”", "Comparing 3 results from price feed services", "Judge scoring 3 candidates", "Local · running ffmpeg on the workspace"), the service it is on, the time elapsed and what it has spent so far. The timeline fills in as each step lands: every call with its service, category and cost; images and clips inline; a Compare block when it tried several services of one kind, with the judge's score, reasons and the winner; the run of any agent it hired, nested. At the end, Spend: what the run cost on each service, and on the agent's page the last 24 hours and 7 days for one that runs on a schedule or serves others. The same stream is GET /runs/:id/events on the runner, aioum run watch in the terminal and aioum_run_watch from Claude: Watch it work.

Projects

A job that takes several passes is a project: one brief, one budget, and stages that each run the agent with the stage's instruction plus what the stages it needs produced, the files and links it returned collected on the way. A stage names the stages it waits for (after, by position); it starts as soon as they are done, beside every other stage that is ready, so a cartoon's character art, voice lines and music all start the moment the script is done and the assembly once all three are. A stage that names none waits for every stage before it. The project's remaining budget is split among the stages started together; one that runs out of its share beside siblings runs again alone with what is left, once. Create one in the Projects panel on the agent's page, typing the stages one per line or letting the agent's planner propose them with their dependencies, with the budget you are willing to spend (the runner creates none without it), press Start, and the panel shows each stage as it runs, with its run, what it produced and its spend, and after 1, 3 on a stage that waits for those. A stage that fails lets the stages beside it finish, their outputs kept, then pauses the project so you can change what comes next and resume; Pause lets the running stages finish. From a shell, aioum project create|start|pause|resume|stages|spend (--stage "Voice lines (after 1)"); from Claude, aioum_project_*. A pipeline is a project on a network of agents, built in one click: Pipelines.

Agents hiring agents

This is how the many are joined. Press Publish as a service on an agent's page and give it a price per call. The stack's node stakes and registers a listing on-chain, and it appears in the marketplace like any other service. On your local development network the node always accepts these listings; on the AIOUM network only when whoever runs the stack started the node with AIOUM_ADMIN_ALLOW_ADD=1, and otherwise the page tells you the node refused. Once listed, another agent adds it as a tool the way it adds a price feed, or finds it in a marketplace search while it runs. The caller pays your agent's price per call, with a receipt; your agent runs, shown in its history as "hired", paying for its own tools from its own budget; you keep the difference between your price and what the run cost. The hiring agent then rates the operator behind your listing as it would any service.

That is how a network of specialists forms without a company in the middle. An agent cannot hire itself, a published agent never finds its own listing in a search, and Take it off the market delists it again.

Who plans

Workflows need no AI at all. An assistant needs a model to plan its turns, and the builder's Which model plans? offers whatever is live:

Which one a Super Agent gets, and the order the builder lists them in, goes by model tier, not by where the model runs: the frontier tier (Claude, GPT-4.1 and GPT-5, Gemini 2.5 and 3 Pro, Grok, and open models of that size such as DeepSeek V3 and Llama 405B), the 70B tier (Llama 3.3 70B, Qwen 72B, Mixtral, and the small API models sold beside them: Haiku, GPT-4o mini, Gemini Flash), the 7B tier (Llama 3.1 8B, Qwen 7B and 14B, Mistral 7B, Phi-4) and the 3B tier (Llama 3.2, Gemma 3 4B, Qwen 3B and under). The tier is read from the model id, a size in the id first (llama3.1:70b), then the family; an id the table does not know ranks with the 7B tier and says so. The highest tier live wins; within a tier your Claude plan (nothing per turn, no key) comes before a listing (paid per turn, no key needed), then the runner's key, then its local model, then the cheaper listing. A runner with qwen2.5:7b beside it and one llama3.2 listing live plans on its own model, and says why: qwen2.5:7b on your node (7B tier) over Planner Ollama · llama3.2 (3B tier). The builder's Which model plans? shows the tier beside each option, best first.

No planner is ours to run: a listing is a node like any other (Run a planner node says who can run one, what they earn and how the runner picks), and a runner is yours to start (Run every part yourself). The automatic pick goes by tier, then kind, then price, then name; a rating and the experience record order the manual picker. Whichever plans, the model only ever sees tool descriptions, prices and results, plus the free marketplace search when the agent may find its own tools. Budgets, deposits, receipts and ratings are handled by the runner, not the model. The planner is told to be economical and to say plainly when a tool failed or the budget ran out, and its prompt carries five more lines, whichever model plans:

• Your node's hardware: the one-line summary from hardware.check (the fresh .deploy/hardware.json on the runner, else the node's own check) with the GPU named, or "unknown … treat it as having no GPU" when neither reached the runner;
• GPU: image and video analysis, frame sampling, model inference over frames, and rendering run on a GPU: your node's NVIDIA GPU when Docker runs with the NVIDIA runtime there, else the GPU rented for the job or a compute:gpu listing; never on a CPU, and never on Apple Silicon for the CUDA jobs;
• Missing parts: when a task needs something no live listing offers, say exactly what is missing (the key or listing) instead of substituting a weaker path;
• Test before you trust: make one small paid call to a candidate before relying on it for a whole stage;
• The network learns: the marketplace search ranks what it finds by what other agents' runs found with each tool for the need (how often it worked, the judge's scores, how well tested), then price, the operator's rating and speed, so the planner names the need in the search; and after a tool served it, note_tool takes one line on how it did for that kind of job, recorded with the receipt and shared with the network once the session settles.

Under the hood

Your runner runs inside your private node (offchain/src/agents, reached at http://127.0.0.1:8770/runner with the node's token). It keeps your agents and runs under ~/.aioum-private/runner, pays through the same x402 rails as any other buyer, and exposes a plain JSON API. A shared runner (A shared runner) answers the same API for the people signed in to it:

POST /super               {owner, prompt, budgetUsdc, planner?, plannerModel?, start?}: the Super Agent from a prompt, its setup started
GET  /super/:id           GET /super/:id/events (SSE: setup · project · stage · run · step · now · run-done · done)
POST /super/:id/continue  {without?}   POST /super/:id/brief {choice,text?}   POST /super/:id/rerun
GET  /super/:id/providers?need=   POST /super/:id/provider {need,serviceId}   POST /super/:id/skills {id}   GET /super/missing?limit=50
POST /super/:id/planner   {planner: "auto" | "marketplace:<serviceId>" | "anthropic" | "openai", plannerModel?}: Model on the Models row, the models step run again
GET  /agents?owner=…      POST /agents           GET|PUT|DELETE /agents/:id
POST /agents/:id/runs     GET  /runs/:id         POST /runs/:id/stop
GET  /runs/:id/events     GET  /runs/:id/spend   GET /agents/:id/spend?period=24h|7d|all
PUT  /agents/:id/schedule POST /agents/:id/publish   POST /agents/:id/unpublish
POST /agents/:id/invoke   (what a published listing calls; waits and returns the answer)
POST /projects            GET|DELETE /projects/:id   POST /projects/:id/start|pause|resume
GET  /skills?q=           GET  /skills/:id       GET /starters?kind=   POST /starters/:id/create {budget} | {budgetUsdc, agentBudgetsUsdc}
GET  /tools (`?view=card` for the short form the app's builder reads) · /planners (the planner listings, the runner's own, and catalogue[]: every model you could plan with, available or with why not) · /wallet · /stats · /health
GET  /experience?serviceId=  (this runner's own copy of what its runs learned about tools)
POST /reviews             {serviceId | nodeUrl + key, requester?}: ask for a review; one request per listing per day per requester; reviewed again when it changed or a day after
                          {serviceId, budgetUsdc, at, signature}: with a budget of their own (up to 5), signed by the listing's operator or the runner's owner
GET  /reviews?serviceId=  (status, scores by tool, latency, price charged, the judge's reasons, when, the reviewer)   GET /reviews   POST /reviews/backfill {limit}

There is no login: agents are grouped by the wallet you connect, or by a local id kept in your browser. Everything the runner does is visible on the Activity page under Agent runs.

If something does not work

• Your own planner is out. The plan at its session limit, the key unfunded, no local model: the run does not stop. The best live planner listing plans it instead, paid per turn, and the log's first line says so and why; the same listing proposes a project's stages. Only with no planner listing live does the runner say "No planner available.": list one from the gallery, run a local model beside the runner, start the runner with a key, or use a fixed-steps agent.
• "The planner listing … is offline." Its operator is not serving; pick another planner on the agent's page.
• "This call costs $… but only $… of the budget is left" or "This agent's budget is used up." Raise the per-run or lifetime cap on the agent's page.
• "Set the budget you are willing to spend." Nothing is created without your budget: the box's Budget (USDC), the builder's two caps, a project's budget, a pipeline's project budget and each agent's cap. Type the number; there is no default.
• A tool shows as offline. Its operator is not serving right now; pick another tool of the same kind on the marketplace, or let the agent find its own tools, since a search only ever returns what is live.
• "The agent runner is not reachable." Your private node, and the runner inside it, is not running. On your local development network, start the stack with scripts/devstack.sh review.

Agents built here pay from the wallet on your node. If the agent is one you already have, Claude on your desk or a loop you wrote, Bring your own agent gives it the same marketplace and a budget from your own wallet. Every service your agents just paid for was listed by someone, and you can be that someone.

Next: Watch it work — the live view of a run, what every step cost, and spend per service and per day.

Watch it work

An agent that is generating images with three services to compare them, rendering the first cut of an animation, or reviewing a draft against the brief should be watchable the way a colleague at the next desk is: what it is on right now, what that step cost, and, when it is done or as it keeps going, what it spent on each service. Every run streams that as it happens; the app, the command line and Claude all read the same stream.

The live view

On the agent's page, the Now strip is the line the runner writes for a person, "Calling FLUX.1 [dev] · text-to-image on Node 0xBcd4…4096", "Comparing 3 results from image services", "Judge scoring 2 candidates", "Local · running ffmpeg on the workspace", "Stage 2 of 5 · Rendering first draft", with the service and tool it is on, the category, the seconds elapsed and what it has spent so far, pulsing while it runs. An AI-planned agent adds one sentence of its own before each call, what it is about to do and why.

Under it the timeline fills in as each step lands, no reload: Paid service · tool with the category badge, the cost and the time, "asked:" and what it returned; Local · tool for a step on your node, free; Skill · name with its price when a skill was loaded; images, video and audio inline as they arrive. When a stage tried several services of one kind, a Compare block sets the candidates side by side, each with its service, cost and time, the judge's score and reasons when a judge scored them, and the Winner marked. When it hired another agent, that agent's run is nested under the step that paid for it, live. A project shows stage chips, 1 · Sources and notes, 2 · Draft, the current one marked.

A run opens with what the agent works from: Your node: Apple M4 · 10 cores · 32 GB unified memory · no Docker · Ollama up (2 models) · ffmpeg with videotoolbox · 636.4 GB free. GPU: Apple M4, 32 GB unified memory., the same line the planner reads. Every heavy step says where it ran: a step on your node carries the optimizer's line, Local · running ffmpeg on the workspace · Tuned for Apple M4: hwaccel videotoolbox; a step the runner sent to a GPU listing reads Sampling frames and running the vision model as a GPU job on a compute listing · ran on Own Gpu (compute:gpu listing, NVIDIA A40) once the listing answered, with the device it used. Frame analysis, inference over frames and rendering never run on a CPU; when nothing offers a GPU the step says so instead of running anyway.

At the end, Spend: a table of every service the run paid, calls and cost, and the total for this run; each step's cost also sits on its row. On the right, the agent's own Spend card keeps the Last 24 h and Last 7 days per service, a bar each, so an agent on a schedule or one that others hire reads as "last 24 h: $3.20 across 5 services". A project's panel has the same under Spend · last 24 h and 7 days, per service.

The stream

The runner serves each run over Server-Sent Events, GET /runs/:id/events: the steps so far, then a step per new step, a now per new line, and done with the run and its spendByService. A project streams GET /projects/:id/events with stage, run, run-done and done as well. Every step carries costUsdc, a doing line and, when it produced media, media: [{url, kind}]; a judge's step carries the verdict it parsed, judge, and the Compare block groups the candidates it scored. ?from=N or Last-Event-ID resumes after a break; a ping every 15 seconds keeps the connection alive.

Spend is kept as hourly rollups per agent, project and service, so GET /runs/:id/spend, GET /agents/:id/spend?period=24h|7d|all and GET /projects/:id/spend?period= answer at once with the total, the calls, the runs, one row per service and one per day.

From the command line and from Claude

npx aioum run watch <run-id>              # one line per step as it happens, then spend per service
npx aioum run spend <run-id>              # what one run spent on each service
npx aioum agent spend <agent-id> --period 24h    # or 7d, all: total, per service, per day
npx aioum project spend <project-id> --period 7d

run watch takes --timeout (600 s) and --from N to skip steps already seen; --json prints one JSON object per event, then the run. From Claude, aioum_run_watch follows a run until it ends or timeoutSeconds passes (then the steps so far, with timedOut: true), and aioum_spend takes one of runId, agentId or projectId with period. In code, the SDK's runWatch, projectWatch, runSpend, agentSpend and projectSpend wrap the same routes.

Next: Skills — the free index, skills for sale per use or one-time, and how an agent loads, discovers and keeps them.

Skills

A skill is a folder an agent loads when the job calls for it: SKILL.md with the instructions, when to use them and how, plus any scripts and files. It is the open format Claude and the open-source skill directories use, and on AIOUM it is a marketplace of its own: 1,505 open-source skills indexed from public directories, free, each with its repo, commit and licence, beside skills anyone lists on a node, per use or one-time. An agent reads a skill's instructions when it needs them, runs its scripts on your node, and can discover skills on its own during a run and keep the ones that worked.

The free index

npm run skills:index in offchain/ reads real public directories with the GitHub API: the known collections (anthropics/skills and the awesome-claude-skills and awesome-agent-skills lists), the agent-skills and claude-skills topics, code search for filename:SKILL.md above a star threshold, and a crypto slice of its own. It fetches each SKILL.md, parses its frontmatter, and writes offchain/skills/index.json: one entry per skill with its id, name, description, tags, category skill:<tag>, source {repo, path, commit, url}, licence and files. The files are cached under offchain/skills/<id>/ only when the licence allows redistribution (MIT, Apache-2.0, BSD, CC-BY, CC0, MPL); every other skill is indexed with a link and fetched from its repo when an agent loads it. GITHUB_TOKEN (or GH_TOKEN, or gh auth token) lifts the rate limit; without one, 60 calls an hour and no code search.

mcpmarket.com's skills directory is a second source: the generator reads its robots.txt and honours it (a one-second crawl delay), then its sitemaps and the newest pages, each giving a skill's name, description, author, category and the GitHub folder it links; those entries are link-only, via: mcpmarket, and their SKILL.md comes from the linked folder when an agent loads it.

The runner reads the index from offchain/skills/ (AIOUM_SKILLS_DIR), re-checked every 30 seconds, and serves it: GET /skills?q=&tag=&category=&limit=&offset= searches the index and the skill:* listings on the marketplace together, GET /skills/:id returns one with its SKILL.md, GET /skills/:id/files every file of an index skill. Categories are crypto, media, writing, research, code, data, social, ai, ops and other, each a set of tags.

The project's own skills ship with the runner. offchain/skills/own.json names their folders with tags, a category and a licence; the runner merges each into the served index ahead of the generator's entries, via: "own", with the name, description and licence its SKILL.md states and every file of its folder, always Files ready, and npm run skills:index never touches them. GET /skills, load_skill, the builder and a pipeline's skill need see them like any index entry; a search describes one as "Ships with AIOUM", and the card shows aioum as its source. Twelve ship, all MIT: aioum-beat-engine, aioum-cartoon-scene, aioum-voice-clone and aioum-motion-compiler (The Beat Engine and cartoon scenes), aioum-localize-service and aioum-distill-model (Localize a service, distill a model), aioum-workflow-optimizer, aioum-warm-gpu, aioum-line-cache, aioum-parallel-writer, aioum-kit-on-demand and aioum-resume-from-failure (Speed up a project). Each is also a marketplace listing (the skill-aioum-* templates: skill.get on the node that ships them, one-time, at the smallest price a listing can carry), so an agent on another node hires it like any listed skill.

In an agent

The builder's Its skills step (and --skills a,b on aioum agent create, skills in an aioum_agent_create spec) adds skills by id: an index id such as anthropics-skills-skills-pdf, or svc:<serviceId> for one listed on a node. How it reaches them is the same three-way choice as services and data: Only the skills I pick, My picks first, then anything it discovers, or Fully loose (--skills-access only|prefer|open, default prefer). Press never on a skill and it is ruled out.

At run start each chosen skill's name and description go into the planner's brief, with a rule: before relying on one, call load_skill with its id to read the full SKILL.md. Its files are put in the workspace on your node under skills/<id>/ (the node's skills.install), so its scripts run there with ws.run. With picks-first or fully loose, the planner also has search_skills (free, eight matches at a time) and keep_skill: a skill it found and used in a run that ends well is remembered as Picked up on its own and offered first next time; the builder lists these with Keep and Removed.

The run log shows every load as Skill · name: "trying name" for a free one, "name · $0.50 · one-time, yours now" on a purchase, "name · bought earlier, no charge" after, "name · $0.05" for a per-use load.

Selling a skill

Anyone can list a skill on a node. The listing type is skill: the node serves skill.get {id}, returning the SKILL.md and the files, and the terms are in pricing:

• Per use (mode: "per-use"): every load is a paid call at the price. Nothing is kept between runs.
• One-time (mode: "one-time"): an agent pays once and keeps the files, in the runner's skill cache for that agent; later loads make no call and cost nothing. The purchase is on the agent as Bought outright, with the date and the service, and goes when the agent is deleted.

The licence line is the seller's: whatever SKILL.md states as its licence is what the listing shows, and the marketplace card and the builder show it beside the price and the terms. An open-source skill from the index shows its repo's licence, or "no license stated".

On the Earn page, Sell a skill takes the folder as a zip or a folder already on your node (Put it on the node: the node's POST /admin/skills answers with the SKILL.md's name, description and licence), then a name, a category tag, the one line agents read, the Terms (Per use or One-time), a price once per agent or per load, the usual test call and go-live. /earn?sell=skill opens on it. From the command line and from Claude:

npx aioum sell skill ./my-skill --mode one-time --price 0.5 --category writing
npx aioum sell skill --node-dir /path/on/the/node --mode per-use --price 0.05

aioum_sell_skill takes dir, files or nodeDir, with mode, price, name, description, category, key and stake. The listing's category is skill:<tag>; aioum skills and aioum_skills show every skill with its terms.

The marketplace's Skills section

Free and paid side by side: each card with its source (the repo with its stars, or "Listed on the marketplace" with the operator), its licence or Live state, One-time or Per use with the price, Files ready or Fetched on use, its tags, and Add to an agent, which opens the builder with the skill added.

Next: Pipelines: agent networks in one click — whole networks of agents with a project for the job, built from what is live.

Pipelines: agent networks you pick up in one click

A job that takes several specialists is a pipeline: a few agents that hire one another, a project with a stage for each step of the work, and a schedule when the work never ends. You pick one on the Deploy Agents page under Or start from a ready-made pipeline, press Use this, type the budgets, and the whole network is built from what is live on the marketplace and connected on your node at that moment. Nothing in it is pretend: a pipeline composes only tools that exist, names what it still needs, and refuses to build until those parts are there, with each one pointing at where it is fixed. No pipeline carries a budget: the project's cap and each agent's cap are yours, typed at Use this, and the runner refuses to build without them.

How a pipeline is built

The agents come in hiring order. The ones that are hired, the researcher, the image maker, the shot maker, are published as listings the moment the pipeline is created, so the agent after them calls them the way it calls any service, one paid call with a receipt, at the price the pipeline sets. The last agent is the lead: the project runs on it, stage by stage, and its page is where you watch the whole job, every hire nested under the step that paid for it.

Every agent gets the live tools of its kind as its picks, with My picks first, then anything it finds, so it may reach for more when the job needs it, within its own budget. Where the job compares candidates, an image judge or a text judge listing scores them against the brief and the winner is kept. Where the work is ongoing, the lead carries a schedule, switched off until you press Start.

What it needs is read from the world, twice: when the pipelines are listed and again when one is created. Three kinds of part:

• a listing live on the marketplace, by kind (image generation, a text judge, an email sending service). When none is live, the card names how many templates in the catalogue would serve, links Earn with one pre-filled, and lists the .env keys those templates need;
• a connector on your private node (the workspace, memory, Gmail, an exchange account or a wallet). Missing ones link to Your node;
• a program beside the node: ffmpeg for video assembly, Playwright with Chromium for screenshots, docker for jobs on your own hardware;
• a GPU, for the video, image and training pipelines. Frame analysis, inference over frames and rendering run on a GPU, never on a CPU: your node's own GPU serves first (read from hardware.check), else a compute:gpu listing that runs jobs (run), the same call on someone else's machine. When neither is there the card reads a GPU for frame analysis and rendering: none on this machine; add a compute key (RUNPOD_API_KEY, …) to rent one, or run the node on a machine with a GPU, and Use this stays off. A GPU price feed under compute:gpu is a listing, not a GPU.

A part marked optional does not stop the build; the card says what happens without it. A required part that is missing disables Use this, and the API answers 409 with the same list, so the CLI and Claude see exactly what to fix.

What one run costs is computed from the live prices of the services each pipeline picked: the paid calls one pass of the whole job makes, plus each hire once. Your node's tools cost nothing. The figure sits on the card and in aioum starters --pipelines as onceUsdc; the ranges below are the catalogue's template prices per call, what a listing of that kind is priced at by the sellers who run one. It is information, not a budget: at Use this you type the project's budget and a cap for each agent (its lifetime cap and its cap per run), and nothing is filled in for you.

The pipelines

Image content (Content). A brief becomes a set of finished images, the best of several services, in your workspace. Art director fetches the references the brief names into images/ref/ and reads them on a GPU (the vision model on your node through hf.run, else the runner's GPU jobs on a compute listing), notes the style in images/ref/notes.md, writes one prompt per image and saves them to images/prompts.md, hires Image maker once per prompt, has the set scored against the brief and redoes the weakest image once when it scores under 70. Image maker generates each prompt with every image service it has, asks the image judge to pick the winner, upscales it and removes the background when the prompt asks for a cutout, downloads the file under images/ and answers with the path, the URL, the service, the score and the reasons. Stages: References and prompts · Make the images · Review and deliver. Needs: image generation (three services to compare; templates $0.04 to $2.73 a call, keys FAL_KEY, HF_TOKEN or REPLICATE_API_TOKEN), an image judge ($0.01 to $0.02, GEMINI_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY), a GPU, the workspace; optional upscaling ($0.02 to $0.63), background removal ($0.02 to $0.18), the Hugging Face models on your node. One run: three generations, two judge calls, one upscale, one hire at $0.30.

Video and animation production (Content). A reference analysed on a GPU, script, storyboard, clips from two video services, voice and music, assembled on a GPU, judged, revised. Director fetches one reference clip into video/ref/ when the brief names a show, a style or a clip, and analyses it on a GPU, never on a CPU: on your node's own GPU it samples one frame a second with ws.ffmpeg and runs the vision model over the frames with hf.run; without one it calls the runner's GPU jobs, analyse_frames, which samples the frames and captions them as a docker job on the cheapest live compute:gpu listing and says where it ran. The style, colours, pacing and framing go to video/ref/notes.md. Then the script and shot list to video/script.md and the storyboard to video/storyboard.md (with a frame per shot when an image service is live); it hires Shot maker per shot and Voice and music once, assembles the cut on a GPU (ws.ffmpeg with your node's hardware encoder, else the GPU jobs' assemble on the listing, NVENC, fetched back into video/cut.mp4), has frames of the cut scored against the brief and remakes the weakest shot once. Shot maker generates each shot with both video services, has the judge pick one and saves it under video/shots/. Voice and music makes the narration with text-to-speech and a track when a music service is live, under video/audio/. The run log names where each heavy step ran: Local · running ffmpeg on the workspace · Tuned for Apple M4: hwaccel videotoolbox on your node, or Sampling frames and running the vision model as a GPU job on a compute listing · ran on Own Gpu (compute:gpu listing, NVIDIA A40). Stages: Analyse references · Script · Storyboard · Clips · Voice and music · Assemble · Review and revise. Needs: video generation (two services; $0.40 to $4.80 a call, FAL_KEY or REPLICATE_API_TOKEN), text-to-speech ($0.02 to $4.50), an image judge, ffmpeg beside the node, a GPU, the workspace with ws.ffmpeg; optional music ($0.05 to $1.88), storyboard images, the runner's GPU jobs (there when a compute:gpu listing that runs jobs is live), the Hugging Face models on your node. One run: six clip generations, one voice, two judge calls, two GPU jobs when a listing serves, two hires at $1.50 and $0.20.

Social media content, posting, analytics and optimisation (Growth, on a schedule). Research, drafts per platform, images, posting through your accounts, the metrics back, the next round adjusted. Trend scout finds five angles with numbers and sources. Post studio drafts one post per platform into social/drafts/<date>.md, with an image per post when an image service is live. Publisher recalls the lessons kept in memory, hires the scout and the studio, posts through each account, later pulls the metrics, scores every post (a text judge when one is live), remembers one lesson per line and saves the round; it never posts the same text twice. Stages: Research · Drafts · Post · Analytics and adjust; then every 6 hours: "Run the next round". Needs: a place to post (X, Telegram, Discord, Farcaster, a scheduler or a webhook; $0.001 to $0.01 a call), social analytics (platform metrics or LunarCrush; $0.002 to $0.01), memory and the workspace; optional trend and news research, image generation, a text judge. One run: three posts, two analytics pulls, three research calls, two hires at $0.10 and $0.20.

Research and writing (Research). A question, sources and papers, notes in your workspace, a draft, a review, a revision. Researcher searches the web when a search listing is live, then the paper indexes, reads the two or three most useful pages in full and writes research/notes.md: one paragraph per source with the title, link, year and the two facts that matter, then five open points; it never cites what it did not read. Writer hires the researcher, drafts to research/draft.md with sources inline, has the draft scored by the text judge or reviews it against the brief itself, and revises into research/final.md. Stages: Sources and notes · Draft · Review and revise. Needs: papers and reference (arXiv, Crossref, PubMed, Wikipedia, Open Library; keyless, $0.001 to $0.005 a call), page reading ($0.003 to $0.046), the workspace; optional web search, news, a text judge, a grammar check. This one runs on the keyless devnet as it ships. One run: three paper searches, three page reads, a news pass, one hire at $0.10.

Lead generation (Growth). An ideal customer profile, a search with enrichment, verified emails, CRM rows and outreach drafts. Lead finder searches and enriches people who match the profile, verifies each email when a verifier is live (else marks them unverified) and writes leads/leads.csv (name, title, company, email, verified, source, link), real people the tools returned and nothing else. Outreach writer files each row in the CRM when one is connected, drafts one two-sentence first message per lead into leads/outreach.md and loads them into an outreach tool as drafts when one is live; nothing is sent. Stages: Profile and search · File the leads · Outreach drafts. Needs: people search and enrichment (Apollo, People Data Labs, Hunter, a leads scraper; $0.005 to $0.78 a call), the workspace; optional email verification, a CRM or a table (HubSpot, Airtable, Notion), an outreach tool. One run: four search calls, one hire at $0.30.

Marketing campaign (Growth, on a schedule). Audiences, copy per channel, images, sends and posts, analytics back, the next wave adjusted. Copy and creative writes each piece in its channel's shape into campaign/copy/, with images when an image service is live. Sender sends each piece once, emails through the sending service and posts through the accounts, and records every send with its id in campaign/sent.md. Campaign manager sets the audiences and channels, hires both, has the pieces scored by a text judge when one is live before sending, reads the analytics, scores each piece and remembers the lessons. Stages: Audiences · Copy and creative · Send and post · Analytics and adjust; then daily: "Run the next wave". Needs: an email sending service (Mailchimp, Brevo, Klaviyo, Kit, Customer.io, Resend, SendGrid, Mailgun, Postmark, SES; $0.002 to $0.005 a call), memory and the workspace; optional a place to post, image generation, analytics, a text judge. One run: two sends, two analytics reads, two hires at $0.20 and $0.10.

SEO (Growth). A site crawled, keyword data, the issues and briefs, drafts, published through the site's API. Site auditor reads the main pages, pulls keyword data for the site's topics and writes seo/audit.md: the issues on each page and five content briefs with target keyword, volume, intent and outline. SEO writer drafts each brief into seo/drafts/ with the keyword in the title, the first paragraph and a heading, and internal links to the pages the audit names; with the site's API connected it publishes each as a draft post and records the ids. Stages: Crawl and keywords · Issues and briefs · Drafts · Publish. Needs: page reading or a crawler ($0.003 to $0.046 a call), keyword data (DataForSEO, Semrush, Moz, Ahrefs; $0.01), the workspace; optional the site's API (WordPress, Ghost, Webflow). One run: six page reads, three keyword calls, one hire at $0.30.

Website build and deploy (Web). Pages built on your workspace, deployed, screenshot with the browser on your node, judged, fixed. Site builder writes index.html, the pages named, one stylesheet and images under site/, readable at phone width, with a generated hero image when the brief wants one. Launch manager deploys the site/ folder through the hosting service, opens the live URL with ws.screenshot, has the image judge score the screenshot against the brief, and when it scores under 75 hires the builder with the fix list and deploys once more. Stages: Pages · Deploy · Screenshot check · Fix and redeploy. Needs: a deploy target (Vercel, Netlify, Webflow, GitHub Pages, Cloudflare Pages; $0.002 to $0.01 a call), Playwright with Chromium beside the node, an image judge, the workspace with ws.screenshot and ws.browse; optional image generation. One run: two deploys, two judge calls, one hire at $0.20; project budget $3.

Notifications and reminders (Everyday, on a schedule). Your rules kept on your node; what is due goes out by push, SMS or Telegram. Rule keeper turns what you want reminded of into one rule per line in reminders/rules.md and remembers each in memory, tagged reminder; it never invents one. Notifier reads the rules and reminders/sent.md, sends each reminder that is due through its channel, once, and appends every send with the time; when nothing is due it says so and sends nothing. Stages: Rules · First check (one test reminder, then what is due); then every 15 minutes: "Check the rules and send what is due now". Needs: a way to reach you (ntfy or Pushover push, Twilio, Bird or Vonage SMS, Telegram, a Slack or Discord webhook; $0.001 to $0.01 a call), memory and the workspace; optional your calendar (the Google Calendar connector), world time. One run: one send, one hire at $0.05. The timer is the runner's agent schedule, the same one every scheduled agent uses.

Email auto-responder (Everyday, on a schedule). Your Gmail inbox read on your node, each mail classified, a reply drafted from what you remember, held for your approval. Inbox desk reads new mail with readGmail, skips what is in mail/handled.md, classifies each mail (needs a reply, informational, newsletter, spam) and hires Reply drafter for the ones that need a reply. Its instructions open with Mode: hold for approval: every draft goes to mail/outbox/<id>.md and nothing is sent. Change that line to Mode: send on the desk's page and it sends with sendGmail and records each in mail/sent.md. Reply drafter recalls what is remembered about the sender and the topic, writes a short reply in the tone your memory keeps, and never promises money, dates or decisions that memory does not back. Stages: Read and classify · Drafts to the outbox; then every 15 minutes. Needs: Gmail on your node with reading and sending (the connector asks for the gmail.send and gmail.readonly permissions), memory, the workspace; optional a text judge. One run: one hire at $0.05.

Crypto trading (Trading, on a schedule). Signals from market data, a strategy, a risk judge, execution through your exchange or wallet within its caps, a journal. Signal desk reads last price, 24 h change, bid-ask, book depth, funding and the fear and greed reading for the pairs in the brief and saves the sheet under trading/signals/. Strategist recalls the journal's lessons and answers with one proposal at most (pair, side, size, order type and price, stop and target, three lines of reasoning, a confidence) or "no trade". Trader hires both, has the proposal scored by the risk judge against the brief's rules (max size, max loss, pairs allowed, no averaging down) and treats any score under 70 as a refusal; only then it places the order through exchange.order or wallet.swap on your node, where the per-order and daily caps you set at connect time are enforced, and a refusal ends the cycle. Every cycle is journaled to trading/journal.md with one lesson remembered. Stages: Signals · Strategy · Risk check and execution · Journal; then hourly. Needs: market data (exchange tickers and books, price feeds, funding, sentiment; three sources; keyless, $0.001 to $0.003 a call), a text judge as the risk judge (required; $0.005 to $0.02), an exchange account or a wallet connected on your node with its caps set, memory and the workspace. One run: four data calls, one judge call, two hires at $0.10 each.

Arbitrage (Trading, on a schedule). Prices scanned across venues and DEXs, opportunities checked against fees and gas, executed within caps, journaled. Price scanner reads the same pairs across every venue it has, DEX quotes for the same size when a DEX listing is live, and the gas price, and saves the table with the widest spread per pair in basis points. Arbitrageur computes the net edge of each spread after the fees the brief states, the slippage at the size and gas for on-chain legs, executes only the legs that clear the brief's threshold through the exchange or wallet on your node, never leaves one leg open (a failed second leg closes the first at market and records it), journals every cycle to arb/journal.md. Stages: Scan · Check with fees and gas · Execute within caps · Journal; then every 15 minutes. Needs: exchange tickers and order books across venues (three sources; keyless), an exchange account or a wallet on your node, memory and the workspace; optional DEX quotes ($0.002 to $0.005 a call), gas prices. One run: four ticker calls, two DEX quotes, one gas read, one hire at $0.10.

Four more run on the project's own skills: Cartoon scene (The Beat Engine and cartoon scenes), Localize a service and Distill a model (Localize a service, distill a model), and Speed up a project (Speed up a project).

Cartoon Studio (Content) hires a studio by the film: a prompt and a length in, the finished cartoon in your workspace, the price of every length on its card (Cartoon Studio: a film from a prompt).

Custom. The same shape wired by hand. Publish an agent on its page; under Advanced on Deploy Agents, in the builder's Its services step, it appears under Hires · your published agents for any agent you build next, and the live judges sit under Judges · score candidates against a brief. Tick the hire, tick a judge, set a schedule under Its budget, and create a project on the last agent with one stage per step of the work.

Money, safety, honesty

Each agent has its own lifetime cap and cap per run, enforced by the runner outside the AI; the project has a budget of its own, and a stage may spend what is left of it. All of them are yours: Use this asks for the project's budget and one cap per agent (its lifetime cap and its cap per run), the API refuses a create without them, and no number is ever filled in for you. A hired agent pays for its own tools from its own budget and keeps the difference between its price and that cost. The trading pipelines execute only through the connector on your node, whose caps are set when you connect the account or the wallet and cannot be raised by an agent; a refusal there stops the cycle and is written to the journal. Every agent's instructions end with the same rule: only report what a tool returned, and say so when one failed or the budget ran out.

Next: The Beat Engine and cartoon scenes — animation as data: a measured grammar, a scene file and a rig, every drawing derived and rendered in seconds on your node.

The Beat Engine and cartoon scenes

A shot maker buys clips from a video service and hopes. The Beat Engine is the other way to make animation: as data. A grammar file holds the timing of a show, a scene file holds what happens, and render.py derives every drawing from the two with a seeded random generator, so the same inputs give the same film and a change to timing, framing or a gesture is one line edited and a render of seconds. Nothing is keyframed by hand and nothing is generated by a model. It ships as the project's own skills aioum-beat-engine and aioum-cartoon-scene, with aioum-voice-clone for the voices and aioum-motion-compiler for a whole film from a screenplay (MIT, under Skills with aioum as their source), and as the Cartoon scene pipeline on Deploy Agents. Cartoon Studio sells the finished film: a prompt in, a cartoon out, at a price per length.

Animation as data

The grammar (scripts/grammar.json) is every animation constant with the file it was measured in: drawings on twos, because 55.6% of the reference's holds are exactly two frames; the hold lengths and their weights; the blink's closed lengths and gaps, 22.5 blinks a minute; the share of the speaker's changes that move the whole head and how far; a head snap at every line start and after a pause of three closed frames; a listener moving one part every 12 to 24 frames; the mouth gate, closed at 30 dB under the line's peak; and ranges, the reference's own spread on ten rows. A new show gets a new grammar: run the same detectors (scripts/detectors/) on its clips and write the constants with their sources. Swap --grammar and the same scene renders in the other show's timing.

The scene is what happens: fps and size, the background (quantised, outlines dilated, saturation set), four framings (zooms of the same background), models (one per character), placements (where each stands and how big), shots (start, end, framing, placement, characters), lines (speaker, start, end, file) and beats (a gesture held over a span, or a cycle), plus a viseme track: one mouth shape per frame per character, read from the audio alone. scene_from_script.py builds it from a voiced script: the lines laid out 0.3 to 0.7 s apart, a master mix, shots cut by speaker runs (a shot under 1.2 s joins the one before), beats from the gesture tags. visemes_local.py builds the track: closed under the gate, else a shape from the spectral centroid. At render, grammar.mouth gates and alternates the shapes: an open shape never repeats on the next drawing.

The rig. A character is a code model or layered art. A code model is a python module with one draw function, cartman(d, cx, gy, u, pose) or kid(d, cx, gy, u, pose, spec): d a PIL.ImageDraw on a transparent layer the size of the frame, cx the centre line, gy the ground line, u the head width in frame pixels, pose the state the grammar drives (view, head and body offsets, mouth, arm, brow, blink or pupil). Layered art is a folder of PNGs cut from one hero drawing, all the same size, with rig.json beside them (size, pivots, mouth_box, eye_boxes) and one mouth_<shape>.png per open viseme; the engine only moves, rotates and stacks the layers, never redraws them. A new character keeps the signature and the pose vocabulary. The example rig (Cartman, Kyle and Stan as code models, a winged brain as layers) and its five voiced lines are the owner's project art, included to learn the contract and check the chain, not for your own production.

The render. render.py walks each shot on twos with a global hold timeline; the forced boundaries are the shot start, a line start, a phrase start after a pause, a blink on and off and a scene beat. On a change the speaker moves its mouth plus one face part, or snaps its head on a phrase; a listener moves one part. Only drawings that differ are drawn; holds repeat the bytes. It prints one JSON line (frames, drawings drawn, seconds, the mouth-change share, head snaps and their gaps) and writes <out>.events.json beside the mp4. It is CPU work in Pillow: python3 with Pillow and numpy, ffmpeg and ffprobe on the PATH, scipy for check.py; no GPU, and the runner's GPU jobs on a compute listing do not run it. The shipped example, a 24-second scene at 1920×1080, renders in seconds on a laptop; a 5-second strip faster still.

Measurement is the verdict

check.py runs the detectors that set the grammar's ranges on the rendered piece (changes per second, snaps, median step, wide steps, blinks per minute, blink length, mouth-change share, head-snap gap) and prints each row inside or outside the reference's range. A row outside names the constant to change; a row inside is settled, and no judge is asked whether the timing is right. shot_sheet.py puts one frame from the middle of each shot on one image, stamped with its time and framing, beside reference frames when you give a folder of them: what an image judge scores and what you read in one look, framing, placement, pose, the mouth at that instant, the look against the reference. Timing and motion are never judged from the sheet.

The commands

From the workspace root, where an agent runs them with ws.run after load_skill put the folder under skills/aioum-beat-engine/:

S=skills/aioum-beat-engine/scripts
python3 $S/scene_from_script.py script/lines.json v1 --out-dir beat   # beat/scene_v1.json, beat/master_v1.wav
python3 $S/visemes_local.py beat/scene_v1.json beat/mouth_track_v1.json
python3 $S/render.py --scene beat/scene_v1.json --strip 0 5 --out beat/strip_0_5.mp4
python3 $S/render.py --scene beat/scene_v1.json --full --out beat/v1.mp4
python3 $S/shot_sheet.py beat/scene_v1.json beat/v1.mp4 beat/v1_sheet.jpg [--refs reference/frames]
python3 $S/check.py beat/v1.mp4 --t0 0 --t1 20

render.py takes --seed N for another take of the same scene, --no-audio, --grammar for another show's timing, --root (the project folder every relative path is read from; AIOUM_BEAT_ROOT) and --rig (another rig's modules; AIOUM_BEAT_RIG). A path not found under the project is read from the skill folder, which is how the base scene's art works from any project. Every file lands in the workspace with a URL under /workspace/.

From a script to a reviewed film

aioum-cartoon-scene is the chain around the engine: the voices, which are the skill aioum-voice-clone, and the loop that gets a scene to a confirmed pass in rounds of minutes.

The script. script/lines.json, a list of {id, speaker, text}; speaker a character key of the rig (cart, kyle, stan, brain in the example); a gesture tag in the text lands a beat on that line: [drag], [cough], [smile], [fists], [raise]. A line is one breath.

Casting from an openly licensed human library. Never a real actor's recordings, never a real person's voice without consent, never a voice from the show. One parquet shard of a CC0 or CC-BY speech set comes from the Hub, hf_hub_download("MushanW/GLOBE_V2", "data/<split>-00000-of-000NN.parquet", repo_type="dataset"): GLOBE_V2 is Common Voice derived, CC0 1.0, with age, gender and accent per speaker, hundreds of speakers a shard. measure.py shard.parquet globe voices/cand_globe.json voices/clips_globe measures every one: median pitch in Hz, brightness (the spectral centroid), age, gender, accent, and up to six clean clips of 3 to 12 s. One speaker per character, by the description: pitch first, then brightness, then age and gender, the top three heard. A boy is a high, bright male voice in his twenties pitched up; a smooth salesman a low, dark voice. The prompt set is one wav per character, voices/prompts/<character>.wav: the speaker's cleanest 10 to 13 s clip, pitched up 2 to 7 semitones where the character asks for it (more sounds like a chipmunk); the prompt's pitch becomes the character's. voices/prompts/SOURCE.json travels with the film: the set and its licence, and per character the speaker id, gender, age, natural pitch, the shift and the resulting pitch, the prompt's length.

Cloning, once, in one process. say.py clones every line from the prompt set with Chatterbox. The model loads once per process and a line takes about 12 s on Apple MPS (faster on CUDA, slower on a CPU), so the whole script goes in one --batch call, never one process per line:

python3 skills/aioum-voice-clone/scripts/say.py --batch voices/batch.json --prompts voices/prompts
python3 skills/aioum-voice-clone/scripts/level.py voices/batch.json

voices/batch.json is [{character, text, out}] with the gesture tags stripped from the text; level.py levels every take. Every take carries a sidecar, <out>.json, with its character, text, prompt and style, and --only-stale clones again only what changed. script/lines_voiced.json is the script with file added per line, tags kept: what the engine takes. normalize.py lines_voiced.json voices/prompts locks a character's lines to the prompt's median pitch when a take drifted; say_kokoro.py, in aioum-cartoon-scene, is the stand-in with preset voices (Kokoro-82M on the CPU, a second a line) for a first timing pass of a long script, never the cast. In the python that runs them: chatterbox-tts with torch and torchaudio, kokoro, librosa, soundfile, numpy, pyarrow, huggingface_hub. Then the engine: scene, viseme track, strip, full render, sheet, rows.

The review loop. One problem per round: name it, change one thing, render, measure or judge, decide. Timing, motion and shape are settled by check.py: a row outside its range is the round's problem, and the fix is a grammar constant. The look goes to the image judge paired with a position swap: the sheet and the reference frames sent twice, the candidate and the reference in swapped positions, the pair's agreement taken; a verdict that flips with the position is noise; act on the single biggest reason. One good score is a sample; two in a row with nothing changed but the seed is a pass. A round is minutes; when it runs long, the problem was two problems. Fixes that do not interact (a placement, a beat, a colour) go in one round; two timing constants one at a time. The voices are the slow step and are made once: re-clone a line only when its text changes.

The Motion Compiler

The Beat Engine animates dialogue over a rig that exists. The Motion Compiler makes the whole film from a screenplay: a fresh cast, fresh locations, bodies that cross a room, sit at a desk, hide in a locker, slip and get up. Nothing is drawn by hand per episode. It is the skill aioum-motion-compiler (MIT).

• Characters from a genome. Five families (kid, round, tall, block, critter), a head in five views from front to profile, a palette, headwear, hair, extras. The director writes the genome from the words that introduce a character, and the same name is always the same character. A rig takes about 1 ms.
• Locations from recipes. Sixteen kinds (bedroom, kitchen, street, bus stop, school hallway, classroom, cafeteria, playground, rooftop, bathroom, living room, store, park, alley, forest, car interior), a time of day, a seed, details, 108 props. The same recipe and seed give the same set. A set carries depth objects: what a character stands in front of, passes behind, sits on or hides in, with doors that open. A set takes 3 to 21 ms.
• Motion from verbs. Sixty, each a function of time with anticipation and settle: walking, running, sneaking, sitting, falling, recoiling, pointing with IK hands, grabbing, throwing; hovering, darting, orbiting and perching for a flyer. Idle, blinking and talking are automatic.
• A director. It parses the screenplay, casts it, times every line from its voice file, stages the bodies so nobody stands on anybody, hides them through doors, cuts the camera by the beat, and validates the scene: an error names the beat it comes from. Staging a three-minute screenplay takes about 3 s.
• A renderer. Skia at 1920x1080, the cast depth-sorted with the set's objects, props and effects, libx264 through ffmpeg. Three minutes of film render in about 16 s on an Apple M4.

The screenplay is plain text: the title, sluglines, action lines in the present tense, a name and its spoken words. A slugline's place carries a set's word, and a character is introduced in capitals with a description:

THE LATE PASS

INT. SCHOOL HALLWAY - MORNING

MINA, a small girl with pigtails and a yellow hoodie, runs in from the left. She slips, falls down, and gets up.

OTTO, a round boy with glasses and a green beanie, walks in from the right. He waves.

OTTO
You're late. Again.

MINA
(shrugs)
The bus left without me. I ran the whole way.

From the workspace root, in a python 3.12 with skia-python, numpy and pillow, ffmpeg on the PATH:

MC=skills/aioum-motion-compiler/scripts
# the staging before a voice exists: every line's length estimated from its words
PYTHONPATH=$MC python3 -m director.direct film/screenplay.txt --out film/scene.json --no-audio
# the voice batch, cloned with aioum-voice-clone, then the staging timed to the voices
PYTHONPATH=$MC python3 -m director.voices batch film/screenplay.txt --out film/voices
python3 skills/aioum-voice-clone/scripts/say.py --batch film/voices/batch.json --prompts voices/prompts
PYTHONPATH=$MC python3 -m director.direct film/screenplay.txt --out film/scene.json --batch film/voices/batch.json --target-seconds 120
PYTHONPATH=$MC python3 -m director.validate film/scene.json film/scene.notes.json
# a range first, the whole film when the range is right
python3 $MC/runtime/render.py film/scene.json film/first10.mp4 --start 0 --end 10 --sheet film/sheet.jpg
python3 $MC/runtime/render.py film/scene.json film/film.mp4

direct writes the scene, scene.notes.json (which beat every shot and event comes from, what it could not read) and timing.json (the seconds of dialogue and of action, scene by scene). --target-seconds tightens what is not dialogue until the film is within 10% of the length; it never cuts a line. render.py --sheet writes the frame sheet a judge or a person reads.

studio/server.py is a page on your machine, port 8575: a prompt becomes a screenplay through your own Claude plan, then voices, staging and a render, one job at a time.

Not yet: lip sync follows loudness, not phonemes; get_up is a stiff pivot; walking into a dumpster needs jump; profile mouths are small.

The Cartoon scene pipeline

Cartoon scene (Content). Voice caster casts from the library, measured, writes SOURCE.json and clones every line in one run of say.py --batch, then levels. Scene maker builds and renders with the engine it is told. With the Motion Compiler it writes the voice batch from the screenplay, stages to the voices, validates, renders a range and then the film with its sheet; a change is a changed sentence, a seed or a length. With the Beat Engine it runs the engine's commands from the workspace root and, given one change (a grammar constant, a placement, a beat, a seed), applies exactly that to the scene JSON or to a copy of the grammar under beat/ and renders again. Director, the lead, chooses the engine and writes the script, a screenplay for the Motion Compiler or tagged lines for the Beat Engine, with a voice description per character (age, gender, pitch, brightness), hires both, and runs the review rounds: the validation or the check.py rows first, never a judge for timing; then the sheet through the image judge twice with the positions swapped; a pass confirmed by a second round; a stop after the confirmed pass or six rounds, saying which. It delivers the mp4, the sheet, the script, SOURCE.json and a round log (problem, change, measurement or score, verdict). Stages: Script · Voices · Build and render · Review rounds · Deliver. Needs: the four skills (aioum-beat-engine, aioum-motion-compiler, aioum-cartoon-scene, aioum-voice-clone), from the runner's skills index; an image judge (four calls; $0.01 to $0.02 a call); ffmpeg and python3 beside the node; the workspace with ws.ffmpeg; optional a GPU on your node's own machine for the cloning (a rented listing cannot run your node's scripts; without one the voices clone on the CPU, and the render needs no GPU). One run: four judge calls, two hires at $0.20 and $0.30.

Cartoon Studio: a film from a prompt

You type what the cartoon is about and how long it runs, and you get the film: the studio writes the screenplay, draws the places and things it needs, casts and clones the voices, stages and renders. It is on the marketplace as Cartoon Studio, and you pay on delivery: a deposit of 0.02 USDC when you order, the rest when the finished film is handed over. A film that fails costs you the deposit and nothing more.

aioum tools --q "cartoon studio"              # the listings and their ids
aioum call <make> make --args '{"prompt": "Two kids both claim the last swing, and the teacher settles it.", "minutes": 1}'
# {"id": "20260929-…", "tier": 1, "collectService": "…", "priceOnDelivery": 0.0453, "deposit": 0.02}
aioum call <desk> status --args '{"id": "20260929-…"}'     # the step it is in, each step's seconds, the cost so far
aioum call <desk> result --args '{"id": "20260929-…"}'     # the preview: 480 wide, a bar across it
aioum call <collectService> collect --args '{"id": "20260929-…"}'   # the film's URL, an mp4, 1920x1080

make takes minutes (1 to 12), characters (simple, drawn from shapes, or illustrated, painted on an art GPU) and movement (recorded or hand-built). Its answer names the listing that hands the film over, one per length and kind of characters, and what is owed there. collect answers the film for a finished job of that length and kind; for any other, a film that is not finished, that failed, or that was collected already, it refuses and nothing is charged. The desk holds the rest at 0.001 USDC a call: status, result, cancel, retry (a stopped film again, from the step it stopped in, without a second deposit), around (the screenplay written again without a piece that could not be drawn; nothing is drawn in its place) and ready. The id sample is a finished film to try them on.

What you pay is the run's cost, the studio owner's surcharge and the protocol's fee, and every listing says which is which:

In USDC. The cost is measured on the films the studio sold, every call as their ledger recorded it: the voice GPU by the second it spoke at its rented rate, the writer's calls, the other planning calls and the judge's at the price of the listings a paid film asks; an illustrated film adds the art GPU and its judge for every character. Starting a GPU that was off is the studio owner's cost, as its idle minutes are. The surcharge is 10% of the cost, at least 0.02 USDC a film. The fee is the protocol's 5% at settlement. The studio records what each film really cost, the GPUs' dollars and the calls by model, and status, result and collect carry it beside the price.

Who makes a paid film. Models that are paid for: the studio owner's own keys first, then LLM and judge listings on the marketplace, chosen the way an agent chooses, by rating, by the model and by price, with the next in line asked when one is out of credit. Never the studio owner's Claude subscription. ready answers whether a writer and a judge are there; when they are not, make answers the studio has no funded model for paid runs: … and nothing is charged. A film written by a small model is made from the kit and the library: nothing new is drawn for it, and every character is a person.

The pipeline. Cartoon Studio (Content) on Deploy Agents runs the whole errand. Producer, the lead, orders the film with make, follows the job with status, takes up a stopped job with around or retry, once, looks at the preview, collects the film at the listing make named and fetches it into films/ in your workspace. Film reviewer samples four frames and has the image judge score them against your prompt. You get the film, its length, the score with its reasons, what was paid and the cost as the studio recorded it. The card shows the price of every length. Stages: Order the film · Watch the job · Review and deliver. Needs: the Cartoon Studio listings, an image judge, the workspace; optional ffmpeg beside the node for the frames. With the aioum-motion-compiler and aioum-voice-clone skills and a GPU, the Producer makes the film on your own node instead and no listing is paid. One run: the deposit, ten status calls and one result, one collect, one judge call, one hire at $0.10.

Reach. On the local development network the node answers on this machine only; on a public network the same listing is reachable by anyone.

Sell your own. Run the studio, name it to your node and list it:

# .env
CARTOON_STUDIO_URL=http://127.0.0.1:8575
CARTOON_STUDIO_SURCHARGE_PCT=10      # your surcharge, percent of the run's cost
CARTOON_STUDIO_SURCHARGE_MIN=0.02    # and its minimum, USDC a film

cd offchain
npm run cartoon-studio -- write --costs table.json   # the templates, from your studio's own cost table
npm run cartoon-studio -- list                       # every listing live on your node
npm run cartoon-studio -- prices

table.json is what the studio's costs.py table prints from its finished films. A changed surcharge is write and list again: a listing whose price changed is taken down and listed at the new one.

Next: Localize a service, distill a model — a paid listing your agents keep hiring, found again as an open-weight copy on your node and proved with the same judge in both orders.

Localize a service, distill a model

Your agents' spend pages show the same listing paid for run after run: a voice, a judge, an image maker, a language model. Two of the project's own skills turn that line into something you own. aioum-localize-service finds the open-weight family of the same task, stands it up on your node or on a GPU listing, runs the same samples through both, has them judged paired with the order swapped, and lists the copy with its parity report, cheaper or faster, only when it holds. aioum-distill-model does it for a language model by training: your own prompts and answers become a corpus, a small student learns them as a LoRA on your GPU or a rented one, and a held-out slice is judged against the teacher the same way. "No local equivalent at this quality yet", with the numbers, is a finished job.

Prove it before you switch

Nothing is replaced on a feeling. The same eight to twenty inputs, the listing's real traffic (GET /runs/:id: the steps whose tool.serviceId is the paid one, their args) or the template's sample when there are fewer, go through the paid listing, one paid call each within the budget, and through the candidate. For each sample the judge gets both outputs as Candidate 1 and Candidate 2 against the brief the listing is hired for, then the same call with the order swapped; then three more calls on one unchanged pair, whose spread is the judge's noise. Every call goes into verdicts.json as the judge answered it, and

python3 skills/aioum-localize-service/scripts/parity.py --paid localize/<id>/paid.json --local localize/<id>/local.json --verdicts localize/<id>/verdicts.json --out localize/<id>/parity.json

answers parity, better, not at parity or inconclusive, with the paired difference, the noise band (the larger of the repeat spread and the spread the position alone caused), the position-swap agreement (75% or more to count; --agree), a position lean when the judge picks the same slot whatever is in it, and both sides' cost and latency. A speech sample is judged on its transcript (an audio:stt listing on both files, the text judge against the script) and on the files when a listing that listens is live; an image on the images (imageUrls); text on the text. A judge that leans, or swings twenty points on unchanged work, is seconded by another judge listing before anything is concluded. Only parity or better is accepted: inside the band, agreeing, no lean, and cheaper or faster.

Localize a service

When. GET /agents/:id/spend?period=7d or GET /projects/:id/spend shows one listing taking a large share of the calls, its category has an open-weight family, and you own the node the copy runs on or hold a compute key. A listing that is a person's account, a data feed, a scraper or a payment rail has no family: stop.

Each family's licence is read on its card before it is used: FLUX.1 dev and F5-TTS's weights carry non-commercial terms, SDXL the CreativeML Open RAIL++-M, Llama the community licence, Qwen a licence that differs by size. Image generation, vision over frames and any CUDA container run on a GPU, your node's own or a rented listing, never a CPU; text and speech run on Apple Silicon or a CPU when hf.install says they fit.

The steps. The contract from GET /tools (serviceId, category, tool, inputSchema, priceUsdc, timeoutMs, template, experience, rating), the template's sample from offchain/templates/<template>.json and what earlier runs found from GET /experience?serviceId=, into localize/<id>/contract.md: the copy must take the same inputs and answer in the same shape, or the agents that hire it cannot swap. The family from the table, with its revision sha and each weight file's sha256 from https://huggingface.co/api/models/<repo>?blobs=true, ws.fetched into source.json. hardware.check, then hardware.optimize {kind: ollama | diffusers | whisper, model} for the quantization, dtype and offload that fit, each with the rule it comes from; hf.install {repo, kind: llm | pipeline, task?, quant?} reads the model's size from the Hub and refuses one the machine cannot hold, naming a smaller variant or a rented GPU; then hf.status {id} until done, hf.list to confirm, hf.run {repo, inputs} per sample with its tuned line kept. A family with its own serving code is a job on a compute:gpu listing, run {image: "<repo>@sha256:<digest>", command, inputs} and status {jobId}, your own machine's through the compute-own-gpu template (Sell your GPU). The outputs go to paid.json and local.json as [{sample, output, ms, costUsdc}], then the judging above and parity.json.

Publish. At parity, one template JSON in offchain/templates/ with the paid listing's category and tool names, keyless: true, local: true, requires (gpu, vramGb, ramGb) from the plan: an ollama adapter with model for a language or vision-language model (the shape of local-ollama-qwen.json), or a compute adapter with images: ["<repo>@sha256:<digest>"] as the allowlist (compute-own-gpu.json). npm run test:templates validates it. It goes live with aioum sell add --template <name> --price <usdc> (aioum_sell_add from Claude), the Earn page with the template picked, or npm run catalogue:bootstrap, which lists a local: true template when the machine meets its requires and what it runs on answers, and says why when it skips it. Price it under the paid listing. The parity report rides with it: the numbers in the template's description, the files at /workspace/localize/<serviceId>/ on your node, and one note_tool on the new listing with the judged score, so the network's experience carries it from the first call. source.json keeps the repo, revision, hashes, licence and its URL, the image digest, the judge listing and its noise band, the sample set and the date.

Distill a model

A language model that answers one kind of prompt well for one person does not need a frontier model behind it.

The corpus. One .jsonl, an example per line: {"prompt", "completion"}, {"messages": [{"role", "content"}, …]} or {"text"}. Three sources, in this order: a file you name in the workspace; the runner's transcripts (GET /runs?limit=200, then each GET /runs/:id, one line per tool step of the paid listing whose result was not an error, ws.fetched into distill/runs/ from your own runner inside the node); or answers generated on the paid listing's tokens, your own prompts through its tool at its price, only where the provider's terms allow it and the brief says so. Under about 200 examples the held-out set is too small to read, and the report says so.

python3 skills/aioum-distill-model/scripts/split_corpus.py distill/corpus.jsonl --out distill --holdout 0.1 --seed 7

drops lines outside the three shapes and repeated prompts, and writes train.jsonl, holdout.jsonl (the teacher's answers), holdout_prompts.txt and split.json (the counts and the seed); the held-out set never shares a prompt with the training set, and the same seed gives the same split. --holdout-n takes a count instead of a share, --min-chars a floor.

Train. hardware.check, then hardware.optimize {kind: "train", model: "<student base>"}: whether this machine trains it (Docker with the NVIDIA runtime, and the memory the run needs with the figure's source) or a GPU is rented, and the settings. A student base is a small instruct model on the Hub, Qwen/Qwen2.5-0.5B-Instruct or Qwen/Qwen2.5-1.5B-Instruct, its card read. Two paths. train.lora {base, kind: "llm", dataset: "distill/train.jsonl"}, with steps, rank and lr defaulting to the plan (500 steps, rank 16, the trainer's documented rate). Or train.distill {teacher: "qwen2.5:7b", student, prompts, system?, maxTokens?} when the teacher is a larger model already in Ollama on your node: it answers every prompt (up to 2,000), the answers land in distill/<stamp>/dataset.jsonl, and the same LoRA job starts. train.status {id} follows the trainer's own log (loss, steps). When the answer carries rent instead, nothing started: it holds the exact run arguments for a compute:gpu listing, the dataset as a public zip URL, since a rented machine cannot read your workspace; without one, the report is the rent arguments and why. Training runs in a container (docker run --rm --gpus all, the dataset at /in, the adapter at /out), never as a script on the host and never on a CPU (Make your own model).

Export and judge. train.export {id, to: "ollama", name} writes a Modelfile (FROM <base> ADAPTER <folder>; base defaults to hf.co/<student base>) and runs ollama create. Every held-out prompt goes through the student, ws.run with curl -s http://127.0.0.1:11434/api/generate -d '{"model":"<name>","prompt":"…","stream":false}' (or ollama run <name>), the answer and its time kept; the teacher's answers are in holdout.jsonl. The text judge scores them paired, both orders, three repeats, and parity.py from aioum-localize-service (load that skill too; its script lands beside this one) gives the verdict, the student's cost at 0. At parity the student is listed like any localized copy: a template in the shape of local-ollama-qwen.json, adapter: "ollama", local: true, keyless: true, requires: {ramGb} from the plan, the category the paid listing's (text:llm) or llm:local-<name>, the system prompt when the corpus had one, the parity numbers and the corpus size in the description, priced under the teacher. Below parity the answer is the paired difference, the band, the held-out count, the loss curve's last value and what to change first: more examples of the prompts the student lost on, a larger student, more steps.

Costs. GPU time: nothing on your own machine, the listing's per-minute rate on a rented one. Judge calls at the listing's price, two per held-out prompt plus three repeats; a corpus generated on the teacher, one call per prompt at its price.

The rules

• Safetensors or GGUF weights only, from a named repo at a recorded revision, hashes recorded; no pickled checkpoints, no weights from a link in a forum. A repo whose card says trust_remote_code is a docker job, never a pipeline on the host.
• Docker images by digest, no host mounts: the compute listing mounts the job's /in and /out and nothing else. Third-party serving code never runs on the host, and nothing is pip installed there outside the venv hf.install manages.
• Never on a CPU what belongs on a GPU: image generation, vision over frames, CUDA containers.
• One judge, both orders, the noise measured first; a difference inside the band is not a difference.
• The licence and the source are recorded beside the copy; every number reported comes from a tool's answer, with its source, and a step that failed is reported as failed.
• Outputs are the provider's to license. Before a corpus is generated on a paid listing's tokens, or its transcripts reused, the provider's current terms on training models with its outputs are checked; where they forbid it, the skill refuses and says so in the report. OpenAI, Anthropic and Google's Gemini API are commonly known to forbid it: check their terms. Mistral, Cohere and xAI: the current API terms. fal, Replicate, Together, OpenRouter and Hugging Face Inference: the served model's licence and the host's terms, both. Meta Llama: the community licence's conditions on derived models. Google Gemma: its own terms of use. A local teacher in Ollama is bound by its own licence only. A localized copy is trained on nothing: the paid listing's outputs go through the judge and are kept as the parity record, and never become training data where the terms forbid it.

The pipelines

Localize a service (Everyday). Candidate stand-up takes the contract, the candidate's repo and how it runs, and the samples: hardware.check and hardware.optimize, hf.install, hf.status, hf.list, then hf.run per sample into localize/<id>/local.json with the tuned line, and the source record from the Hub with the revision, hashes and licence. A model hf.install refuses runs as a job on the GPU listing when there is one, else the refusal and the smaller variant it named are the answer; with no GPU live, an image, video or vision-language candidate stops with the rent line, never a CPU. Localizer, the lead, reads the contract, builds the sample set, pays the listing once per sample, hires the stand-up once per candidate family, judges paired, runs parity.py, and at parity writes localize/<id>/template.json and parity.md and says exactly how the copy goes live; anything else is "no local equivalent at this quality yet" with the numbers. Stages: Read the contract · Sample set · Candidates · Paired judging · Publish or report. Needs: the skill; a judge of the task's kind, an image judge or a text judge (twelve calls; $0.005 to $0.02 a call); the hardware check and the Hugging Face models with Ollama on your node; the workspace; optional speech-to-text for speech candidates (four calls; $0.01 to $0.135; without it, speech is judged by the text judge on the script and by ear from the files, no word-error rate) and a GPU, your node's own or a compute:gpu listing (without it, text and speech candidates run through Ollama and hf.run when they fit, and an image, video or vision-language candidate is reported with the rent line). One run: twelve judge calls, four speech-to-text calls and two GPU jobs when those serve, one hire at $0.20.

Distill a model (Everyday). Corpus builder builds distill/corpus.jsonl from your file, the transcripts, or the teacher where its terms allow, and splits it; it answers with the counts from split.json, the source and the terms it checked, and refuses to generate on a provider whose terms forbid it. Distiller plans with hardware.optimize (kind: "train"), trains with train.lora or train.distill and follows train.status, or hands the rent.run arguments to the GPU listing among its tools and fetches the adapter back; with none, it reports the arguments and why, and stops. Evaluator and publisher, the lead, hires both, exports with train.export, runs the held-out prompts through the student, judges paired with the text judge, runs parity.py, and at parity writes distill/template.json and says how it goes live; otherwise the verdict line with what to change first. Stages: Corpus · Plan and train · Evaluate · Publish. Needs: both skills; the hardware check, the train connector and the Hugging Face models with Ollama on your node; a GPU for training, your node's own or a compute:gpu or train:job listing; a text judge (eight calls; $0.005 to $0.02); the workspace; optional a language-model listing as the teacher (twenty calls; $0.003 to $0.10; without it, nothing is generated). One run: eight judge calls, one GPU job when a listing serves, twenty teacher calls when one is live and its terms allow, two hires at $0.10 and $0.20.

Next: Speed up a project — where a project's time went, what runs at once, and the gain measured on the next run.

Speed up a project

Your project finished, and it took longer than the work in it. The runner kept every second: when each stage started and ended, every call with its seconds and cost, the runs that failed and ran again. The workflow optimizer reads that record, says where the clock went, changes what the record proves safe, and measures the next run against the last.

One production day is where its rules come from. A cartoon episode took 35 minutes in the morning and about 4 by night, with the same budget, the same judge and the same bar.

Where the time went

aioum project optimize <id>

or POST /projects/:id/optimize on the runner, or aioum_project_optimize from your own AI. Nothing is changed by it. The answer opens with the measured wall clock and cost, then the shares. A project of five stages that ran one after another, script 60 s, character art 120 s, voice lines 90 s, assembly 50 s and judging 30 s, reads:

Measured: 5.8 min on the clock over 5 stages, 0.08 USDC
  50% the planner's turns (2.9 min)
  23% Slow Images · generate (80 s)
  14% Voices · speak (50 s)
  9% Your node · ws.ffmpeg (30 s)
  4% Image Judge · judge (15 s)
Predicted with the safe changes: 4.3 min (90 s less), 0.08 USDC; with every recommendation: 3.8 min, 0.09 USDC
Safe to apply: stage 3 (Voice lines) does not need stage 2 (Character art): they run at once · saves 90 s
Recommended: Slow Images is slow for image:gen: Fast Images (listing #41) answers in 20 s against 80 s, rated 85 against 80 · saves 60 s · +0.01 USDC

The clock is the time a stage ran. A pause between stages is reported beside it and never counted. A run that failed and ran again is counted, under its own name.

What it changes, and what it leaves to you

Every change comes from a fixed set, with the seconds it saves, the evidence, and the exact setting.

With --all the optimizer makes the changes in the right-hand column too:

aioum project optimize <id> --apply --all

Each line of the answer opens with Done or Not done and the reason. Only stages that have not run, or that failed, are changed.

A stage is freed from an earlier one only on the record: both ran, and nothing the earlier one made is in what the later one was given or wrote. No link, no file, no six words in a row, no two figures the earlier stage reported. A stage whose instruction names an earlier one keeps it: by a word of its title, by its number, or as "the first two stages", "the stage before", "both stages". A stage that never ran is a recommendation.

Your budget is never raised. A listing your agent's access rules exclude is never proposed. The judge, the quality bar, a sample stage and a review round are never touched.

Apply, run again, measure

On a paused project with stages left:

aioum project optimize <id> --apply
aioum project resume <id> --wait

The changes are written to the stages that are not done. Done stages stay.

On a project whose stages are all done:

aioum project optimize <id> --again
aioum project start <copy id> --wait
aioum project optimize <copy id>

--again makes a draft copy with the same agent, brief, budget and review settings and the safe changes written in. After the run, the last line opens with Measured after the change: the wall clock and cost of the run, the seconds and the share it took less than the run before, and the prediction beside it.

The prediction is the sum rule. Stages that run one after another add up. Stages that run at once count as the longest of them. In the example: 60 + the longer of 120 and 90 + 50 + 30.

A stage's own limits

{ "title": "Voice lines", "instruction": "Speak every line.", "after": [1],
  "parallel": { "calls": 12, "sessionsPerService": 4, "together": ["Voices"] } }

calls, 1 to 16: how many of one turn's calls run at once. sessionsPerService, 1 to 8: how many sessions the stage's run holds with one listing, never past what its operator has free. together: the listings whose calls go in one turn. Without parallel the runner's own limits stand: 8 calls at once, 3 sessions a listing, 2 calls in flight on one upstream.

The pipeline

Speed up a project, among the ready-made pipelines on Deploy Agents, does the whole round from a project id. A Profiler reads the record. The Workflow optimizer writes the plan, applies what is safe, runs the project again and reports the measured gain, with the recommendations left for you to decide. It needs the aioum-workflow-optimizer skill, python3 and the workspace on your node. A GPU is optional. The run it starts spends from the budget of the project it speeds up.

aioum pipeline create speed-up-project --budget <usdc> --agent-budget profiler=<usdc> --agent-budget optimizer=<usdc> --input "Speed up my project <id>"

The patterns, as skills

Each pattern of that day ships with the runner and is listed on the marketplace, one-time, MIT.

Voice cloning took 25 s a line on an Apple M4 and 1 to 2.5 s on a rented GPU. One GPU saturates at about two workers; past that, a second GPU adds in full.

Next: Your node: workspace, models, wallet and accounts — what runs on your own machine, unmetered, and how agents reach it.

Your node: workspace, models, wallet and accounts

One machine is yours: it runs your private node, and everything on it is a tool your agents get beside the paid listings, free, unmetered and private. A workspace with files, a shell, a browser and ffmpeg; models from Hugging Face installed on your hardware; a wallet and an exchange account with caps you set; your ad, analytics and publishing accounts through your own OAuth apps; your AI subscriptions and keys; the skills an agent loaded; a trainer for models of your own. The marketplace never sees any of it. The marketplace page shows them under Your node, one card per connector with Connect or Install, and the builder's Your node step lists their tools for an agent to tick.

Start the node in offchain/ with npm run private-node (Your private node). The runner reaches it at AIOUM_PRIVATE_NODE_URL (http://127.0.0.1:8770) with the token from ~/.aioum-private/token; the app asks for that token once, under Your node, when it runs on another machine. A run's log shows every step on your node as Local · tool, free.

The workspace

~/.aioum-private/workspace (PRIVATE_NODE_WORKSPACE) is the folder your agents work in. Tools: ws.list {path?}, ws.read {path}, ws.write {path, content}, ws.run {cmd, timeoutMs?} (a shell inside the root, 120 s and 1 MB of output by default, up to 600 s), ws.fetch {url, path} (a download), ws.screenshot {url, path?, fullPage?} and ws.browse {url} (a headless Chromium through Playwright: npm i playwright && npx playwright install chromium in offchain/, or PLAYWRIGHT_MODULE), and ws.ffmpeg {args} (ffmpeg on the PATH, with the hardware decoder the optimizer found put in front of the input). A path outside the root is refused. Every file has a URL, /workspace/<path> on the node behind its token, so a result an agent renders shows inline on its page and a pipeline hands files from stage to stage. Whatever an agent writes, downloads, screenshots or renders lands here; skills it loads go under skills/. A workspace file reaches the GPU rented for a project too: name it as a job's input (/workspace/<path>) and the runner ships it to the pod.

Hugging Face models on your machine

hf.install {repo, kind, task?, quant?} installs a model from huggingface.co:

• kind: "llm" pulls it into Ollama, ollama pull hf.co/<repo>[:<quant>]. Ollama must answer at OLLAMA_HOST (127.0.0.1:11434); else "Ollama is not reachable … Install it from https://ollama.com/download and start it".
• kind: "pipeline" makes a Python venv at ~/.aioum-private/models/venv with transformers, diffusers, torch, torchvision, accelerate, safetensors and soundfile (a few hundred MB the first time), downloads the model, and serves it through a small worker on 127.0.0.1:8790 that loads pipeline(task, model) on demand. Without python3: "install Python 3.9 or newer".

The install is a job: the answer carries its id and hf.status {id} reports progress and the log; nothing is pretended. Before anything downloads the node reads the model's size from the Hub and refuses one your machine cannot hold, naming the largest quantization that fits, a smaller variant of the family, or a rented GPU (the compute:gpu listings). hf.list shows what is installed and whether Ollama, Python and the worker are up; hf.remove {repo} removes one; hf.run {repo, inputs} runs it (an LLM through Ollama's /api/generate, a pipeline through the worker; images and audio land in the workspace under hf/), tuned for the machine. On the marketplace, the Hugging Face models card takes a repo id, LLM, through Ollama or Pipeline, in Python, and Install.

What the machine can do, and the settings that fit it

npm run hardware:check reads the machine, CPU cores, RAM, GPUs and VRAM (nvidia-smi, rocm-smi, Apple Silicon through system_profiler), disk, Docker and the NVIDIA runtime, Ollama, ffmpeg's hardware encoders, python3, and writes .deploy/hardware.json. The catalogue reads it: a local template with requires (gpu, vramGb, ramGb, cpus) is listed only when the machine meets it, else skipped with "needs a GPU with ≥ 12 GB (this machine: none); rent one: the compute:gpu listings". hardware.check {refresh?} on the node shows the same report.

hardware.optimize {kind, model?, …} gives the settings that fit, kind one of ollama, diffusers, whisper, ffmpeg, docker or train, each rule cited from the project's own documentation: the largest quantization and context that fit for Ollama; dtype, attention slicing, VAE tiling and CPU offload for diffusers; compute type and model size for whisper; the hardware decoder and encoder for ffmpeg; --gpus, shm size and memory for docker. hf.run, the compute listing, ws.ffmpeg and the trainer apply them on their own, and a run's log says what was set: "Tuned for Apple M4: fp16, attention slicing". npm run hardware:optimize -- --kind diffusers --model <repo> prints the same from a shell. The full story, with training: Make your own model.

Task and hardware optimizers

Two listings anyone can run, and the runner's built-in fallback when none is live. The task optimizer (optimize:prompt, templates optimize-prompt-openai, -gemini, -anthropic) is a language model behind one system prompt: optimize.prompt {prompt, budgetUsdc} returns {brief: {goal, deliverable, constraints, qualityBar, references, kinds}} as JSON, nothing the person did not say and no invented numbers. The hardware optimizer (optimize:hardware, template optimize-hardware, keyless, the optimizer adapter) runs the rules of hardware.ts and optimize.ts on what a buyer posts: optimize.hardware {needs, hardware, keys?, budgetUsdc?, hours?, prices?} with the needs as kinds (["video:gen", "audio:tts", "compute:gpu"]), the buyer's own hardware.check report and the names of the rental keys it holds, never a value. It answers {plan: [{need, where: node | rent, why, stage, estimates}], estimates: [{stage, local: {can, minutes?, why}, rented: {minutes, why}, where, assumes}], jobs?, rent?: {provider, template, instance, pricePerHour?, hours, keyed, withinBudget?}, missingKeys, localMaxMin, rentedMinutes, line, rules}, localMaxMin (10 minutes per stage), job (the figures: clips, seconds, fps, the cut's length, the answer's tokens, the training steps) and jobs (a live compute listing that runs jobs) optional. The rules: frame analysis (4 GB) and render (12 GB) are CUDA containers, so a node runs them only with an NVIDIA GPU under Docker's NVIDIA runtime, never Apple Silicon or a CPU; assembly is ffmpeg with the encoder the build lists, on the node; a local model runs over MPS, CUDA or the CPU when it fits and answers within the limit; a training run takes trainingPlan's figure. Every estimate is stated work over a stated class: captions per second, render frames per second, memory bandwidth for a model's tokens, training steps per second, for Ampere-or-newer NVIDIA, Volta and Turing, older NVIDIA, Apple Silicon over MPS and a CPU, plus a container's fixed start (120 s rented, 60 s on the node), each rule naming its source (the NVIDIA compute-capability list and A100 datasheet, Apple's M4 memory bandwidth, llama.cpp's bits per weight, gpu-jobs.ts's 1 fps and 24 fps, the NVIDIA encode matrix: A100 and H100 carry no NVENC, and a rented pod's own probe of h264_nvenc at start, which moves the assembly's rented figure to the libx264 rate where the session will not open) and saying which figures are ours. A stage over the limit, or impossible on the node, leaves it: to the job listing when one is live, else to the first provider whose key the buyer holds, named for its instance and price even without a key. This Mac, a video job, no key: video:gen and compute:gpu rent, the rest stays, and the line reads "Hardware: rent a GPU for frame analysis and render (your M4 cannot run the CUDA jobs; assembly stays on your node) · RunPod GeForce RTX 4090, about 7 min · missing key: RUNPOD_API_KEY (or VAST_API_KEY, LAMBDA_API_KEY, DIGITALOCEAN_TOKEN)". With a RunPod key: "Hardware: renting a GeForce RTX 4090 on RunPod for frame analysis and render (…) · ~$0.34/h, about 7 min, 1 h planned". The runner's setup calls a live one first, takes its answer when it carries the estimates, and applies the same rules itself otherwise (Build an agent network).

A wallet and an exchange, with caps

Wallet holds an EVM key, encrypted on the node: wallet.connect takes a private key or a recovery phrase, the chain id (Ethereum, Base, Arbitrum, OP Mainnet, Polygon, BNB Chain, Avalanche), its RPC URL, and two caps, Most one transaction may spend (USD) and Most all transactions may spend per day (USD). Tools: wallet.address, wallet.balance {token?}, wallet.send {to, amount, token?}, wallet.swap {sell, buy, amount, slippageBps?} (a 0x quote, ZEROX_API_KEY on the node), wallet.sign {message}, wallet.execute (a transaction a quote gave: exact allowance, simulation, receipt) and wallet.signOrder (a CoW order). Exchange holds API keys for Binance, Coinbase, Kraken, Bybit or OKX, or Alpaca for US stocks and ETFs on your own brokerage account (paper money unless you say live), with the same two caps: exchange.balances, exchange.ticker {symbol}, exchange.orderbook {symbol, depth?}, exchange.order {symbol, side, type, amount, price?}, exchange.cancel {id}, exchange.orders, each signed on the node the way the venue documents.

A cap of 0, the default, refuses every spend: an agent can look but not move money. Spends are valued in USD through the chain's Chainlink feed, or the venue's own ticker; on a chain with no feed the caps apply in the asset's units. A refusal names the cap and today's total; the day resets at 00:00 UTC. No agent can raise a cap: only you, by connecting again. The trading pipelines and pay in any token run through these tools and stop at these caps.

Your accounts

Gmail and Google Calendar connect through a Google OAuth client in the node's environment (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET), asking for gmail.send and gmail.readonly, or calendar.events: sendGmail, readGmail, createGcalEvent. The other accounts are OAuth apps you make at the provider and paste into the card: the card says "Make an app at the provider with this callback URL, then paste its credentials here", and the callback is <node URL>/oauth/<provider>/callback, http://127.0.0.1:8770/oauth/googleads/callback on a laptop, PRIVATE_NODE_PUBLIC_URL in front of it on a server. Connect opens the provider's consent page; the tokens land on your node, encrypted, and renew themselves.

Agent inbox gives the agents an email address of their own on AgentMail (an API key from agentmail.to; free for three inboxes): receive, read, reply, send, and wait for the next message. The key stays on the node; marketplace-derived content is never sent without your say.

oauth.call {provider, method, url, body?, headers?} reaches any endpoint of a connected provider with its token. The builder's Its data step shows every connected account, and their tools sit under Your node.

Your subscriptions and keys

You pay for a Claude plan, or you hold an API key. Set it once on your node and your own agents think with it: nothing per call on a plan, no key in any file an agent can read. They are yours alone. They are never listed, never sold, in no agent's list of tools, and an agent that belongs to anyone else is refused.

Under Your node, the Subscriptions and keys card shows each one with its state: Connected and the model that answered, Limit reached until 14:00, Not funded, Not reachable with the reason. Add asks what it is and, for a key, the key, then makes one small real call: nothing shows as connected before that call answered. Test makes the call again and says the model, the seconds, and for a plan whether a usage limit is active. Take keys from your .env lists the keys found there by name; tick the ones your node takes. A key goes to your node, is kept encrypted there, and is never shown again.

Order. Planning, judging, writing and your studio each have an order. The first in it is asked. At its usage limit or out of credit it is marked with the reason and the time it resets, and the next is asked; the job goes on. One you leave out of a purpose is never asked for it. Until you set an order it is your plan, then your key, then your local model. Open Order on the card and move them with the arrows.

aioum subs add claude-plan --model fable
aioum subs add anthropic --key-env ANTHROPIC_API_KEY
aioum subs add openai --key-env OPENROUTER_API_KEY --base-url https://openrouter.ai/api/v1
aioum subs add ollama
aioum subs list
aioum subs test <id>
aioum subs model <id> fable            # the model it asks for from now on; none: its own default
aioum subs use planner <id> <id>
aioum subs import                 # the keys in your .env, by name
aioum subs import FAL_KEY         # your node takes this one and tests it
aioum subs owners --add <owner id>
aioum subs remove <id>

Through MCP the same are aioum_subs_list, aioum_subs_add, aioum_subs_test, aioum_subs_remove, aioum_subs_use and aioum_subs_import.

The card adds your owner id, the one your agents carry, when you add a subscription; aioum subs owners --add names another of yours. The runner reads your node at its start and every two minutes, so a new login or a new key is used without a restart (AIOUM_AGENTS_SUBS=0 turns the reading off). With the node stopped the runner plans as before: Claude Code found on this machine, ANTHROPIC_API_KEY, a local Ollama.

On the node the tools are subs.list, subs.add {kind, label?, secret?, baseUrl?, path?, model?, owner?}, subs.remove {id}, subs.test {id}, subs.ask {id?, purpose?, system, prompt, schema?, images?, model?}, subs.use {purpose, order}, subs.import {names?} and subs.owners {add?, remove?}. They answer only a request that carries your node's token, and tools/list, /health and /connections never name them.

Your own runner

Your node runs an agent runner of its own. It starts with the node, comes back by itself when it stops, and stops with the node. Your agents, their projects, their runs and what they spent stay on your machine, in ~/.aioum-private/runner/.

Its wallet is yours. The runner pays every call your agents make from the wallet connected on your node. The key stays encrypted on the node and is handed to the runner as it starts: no file, no log and no command line holds it. What your agents spend is bound by the budget you give each one; the wallet's two caps bind the wallet.* tools. On the local development network, with no wallet connected, the node makes one, keeps it encrypted, and funds it with gas and 100 test USDC. On any other chain you connect your wallet first, and the runner starts with it.

It works for one owner. Everything it holds is its owner's: the wallet's address, or the id in PRIVATE_NODE_OWNER. A request that names another owner is refused. The runner listens on 127.0.0.1:8771 and answers only your node's token.

It plans with what you already have. The subscriptions and keys on your node are its planners, in your order, with nothing to set up.

The app finds it at your node. Under Your network, My own runner shows the runner's wallet, what the wallet holds and what it plans with. Use my own runner points the app at it, and In use shows once it is. The app needs one address, your node's: the runner answers under /runner there. On the machine that runs the app, the app reaches your node with the token from disk. For a node on another machine, put its address under Advanced and its token under Your node.

TOKEN=$(cat ~/.aioum-private/token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8770/runner          # running or not, its wallet, its balance, its planner
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8770/runner/agents   # the runner itself, behind your node's token
scripts/devstack.sh status                                                   # the row own-runner: its state, port and folder

PRIVATE_NODE_RUNNER=0 starts the node without a runner; PRIVATE_NODE_RUNNER_PORT moves its port. A snapshot holds the runner's records with the rest of your node, and npm run network -- counts names them as own runner.

Your agents come with you. The agents you made before are on the runner you used then. Under My own runner the app says how many wait there, and Bring my agents over copies them: your agents, their projects, their runs and their spend, under the ids they had.

aioum node runner import --dry-run     # how many, nothing written
aioum node runner import

Nothing is taken off the runner they come from. An agent that is published there goes on answering its listing there; its copy on your runner is not published. A project that was running is paused on your runner: your wallet pays for nothing you did not start.

Selling from your node. Go live on Earn with no selling node of your own at hand, and your private node starts one: the catalogue node's code as a child of your node on the port after its runner's, your wallet its operator, the listing you went live with its catalogue. The keys the listing needs are kept under ~/.aioum-private/selling/, readable by you alone, and handed to the selling node as it starts; your wallet's key goes over a pipe and never into a file, a command line or an environment a process listing shows. It puts up 100 ZAI of your own and the listing's bond, and the staking node backs the rest to the floor; from then on the app reads your listings, their backing and their live state from that node. It comes back with your node and stops with it. PRIVATE_NODE_SELLING_URL is the address buyers reach it at on a real network; PRIVATE_NODE_SELLING_PORT moves its port.

Start at login. Off unless you switch it on: Your network, Start my node at login. Your machine then starts the node, and the runner inside it, when you log in: a launch agent on macOS, a systemd user unit on Linux. The file it writes carries the node's settings and no key, token or passphrase; a node that opens its secrets with a passphrase from its environment cannot be started this way, and the switch says so. On macOS a program started at login is kept out of ~/Downloads, ~/Desktop and ~/Documents: keep the node elsewhere, or grant Full Disk Access to node. The switch names that when it applies.

aioum node autostart          # on or off, the file, what stands in the way
aioum node autostart on
aioum node autostart off

Skills and training

skills.install {id, files?} puts a skill's folder in the workspace under skills/<id>/, from the runner's index or the files an agent hands it, so the skill's scripts run with ws.run (Skills); skills.list shows what is there. The train connector runs real trainers in a container: train.lora {base, kind, dataset, …} for a language, image, speech or video model, train.distill {teacher, student, prompts} for a student made from an Ollama teacher, train.status, train.list, and train.export {to: workspace | huggingface | ollama}; when the machine cannot run it the answer carries the exact run arguments for a rented GPU (Make your own model).

Next: A shared runner — when you would rather not run your own: a runner someone else offers, paid from your own account inside a cap you sign.

A shared runner

A runner runs your agents: it plans their steps and pays their calls. You run your own inside your node, or you pick a shared one. A shared runner is a listing like any other: anyone offers one, you choose by its price for a run, its rating and who operates it, and you leave when you like.

It never holds your money. Your own account pays, inside a cap you sign.

What it can do with your money

You authorise a shared runner once. Your smart account grants the runner's spending key a cap and an expiry, and the chain enforces both.

With that key the runner:

• opens payment sessions from your account with the services your agents call, up to the cap, until the expiry;
• signs the payments inside those sessions;
• charges its fee: one paid call per run to its own listing, at the listing's price, named in the run's first line before any work starts.

What it cannot do

• Move your money anywhere but into a payment session. Your account lets the key make one call, opening a session, and refuses every other.
• Spend past the cap, or after the expiry. Your account refuses the session.
• Spend after you revoke. The runner reads the key's state from the chain before every session and every payment, and your account refuses a revoked key on its own.
• Keep what a session does not use. It returns to your account when the session settles.
• Show your agents, projects or runs to anyone else, or theirs to you. Every record belongs to the address that signed in.
• Sell your agent. A listing made there would be the operator's, and so would its earnings. Run your own runner to sell one.

The cap is the most a runner can spend, whatever it does. Set it to what the work is worth. It counts what the key moves into sessions, so when it is used up you authorise again.

On a shared runner an agent plans with a planner listing from the marketplace, paid from your account, or runs as a workflow. The operator's own keys and subscriptions stay the operator's.

Pick one

In the app, open Your network. Your agent runner lists your own runner and every shared runner the directory knows. Choose one, set the spending cap, and press Sign in and authorise: your wallet signs a message, then the grant. Advanced holds how long the cap lasts, Revoke and Sign out.

From the command line:

aioum runner list                          # address, price for a run, rating, operator
aioum runner use https://runner.example    # use this one from now on
aioum runner login                         # your wallet signs a message; nothing is paid
aioum runner authorize --cap 5 --days 7    # your account grants the runner's key 5 USDC for 7 days
aioum runner status                        # the fee, your account, the cap, spent, left
aioum runner revoke                        # the key is dead on chain; the runner forgets it

aioum runner use own returns to your own runner. authorize deploys and funds your account when that is still to do, and sets ETH aside for gas where your account pays its own. Run it again to change the cap or the expiry.

revoke needs your wallet and the chain, nothing else. It works with the runner gone.

Offer one

Start the runner in shared mode, with a secret of your own that seals the keys it holds:

cd offchain
AIOUM_AGENTS_MODE=shared \
AIOUM_AGENTS_KEYS_SECRET=<your secret, 16 characters or more> \
AIOUM_AGENTS_URL=https://runner.example \
npm run agents

Then list it, with your price for a run:

aioum sell add --template shared-runner --price 0.002 \
  --env AIOUM_SHARED_RUNNER_URL=https://runner.example

The listing carries the runner's address, your price and your operator account. People find it under aioum runner list and in the app, and the fee of every run reaches you through the same paid path as any call.

On the local development network scripts/devstack.sh review starts one on port 8562 and lists it at 0.002 USDC a run. What a person's run learns about its tools reaches the directory like any runner's: the record is signed with the person's spending key, and the directory checks that key against the account that paid.

The runner's own wallet pays for nothing of a person's. It keeps each person's key sealed in user-keys.json and each sign-in as a hash in sessions.json, both beside its other records.

Your own runner, behind a token

AIOUM_AGENTS_MODE=own is a runner for one owner. With AIOUM_AGENTS_TOKEN set, every request carries Authorization: Bearer <token>; with AIOUM_AGENTS_OWNER set, a request that names another owner is refused. The command line sends the token from AIOUM_AGENTS_TOKEN.

Next: Swap at the best rate, and pay in any token — turn what your wallet holds into what a service takes.

Swap at the best rate, and pay in any token

Your agent needs USDC for a service and the wallet holds ETH; or you want 0.5 ETH turned into USDC on Base at the best price anyone offers right now, without picking an exchange. One module does both: it quotes every live swap and bridge listing that can do the pair, prices each quote's gas and fees through Chainlink, throws out anything off the Chainlink price, and carries the best one out through the wallet on your own node, within the caps you set when you connected it. Every quote it saw and every choice it made is written down.

The swap module

Ask for a swap in words, swap 0.01 ETH to USDC on chain 8453, or bridge 500 USDC on chain 1 to chain 8453, and the runner's built-in tool Best-rate swap (category swap:best, tool best, free to call; the quotes it makes are paid calls to listings) does the rest:

1. Quote everything that can do the pair. Same chain: the DEX aggregators, Velora, Uniswap's trading API, 0x, 1inch, KyberSwap, and CoW Protocol. Across chains: LI.FI, Socket, Across, deBridge and Squid. Each quote is one paid call to that listing, from the run's budget, never a call to a provider directly; the listing's template says how to read its answer. Only live listings are asked, so the set grows with the marketplace.
2. Price the whole cost. Amount out after the quote's fees and the gas it needs, gas valued with the chain's Chainlink feed, on Ethereum, OP Mainnet, BNB Chain, Polygon, Base, Arbitrum One and Avalanche. A feed older than 36 hours is refused: "refusing to price the swap on it".
3. Guard against a bad price. A quote more than 3% below the Chainlink fair value is dropped ("output $X is Y% below the Chainlink fair value $Z"), and so is one more than 5% above it: "a quote that good is not trusted".
4. Choose the best net amount and, with execute: yes, carry it out through the wallet on your private node. The allowance given to the swap contract is exact, the transaction is simulated with eth_call before it is signed ("the transaction reverts in simulation; nothing was sent" is the refusal), the receipt is checked and so is what arrived: "the swap delivered less than its minimum" fails the swap. A CoW quote is signed as an order and posted to the orderbook instead of sent. A bridge is followed on its status endpoint every 15 seconds, up to 20 minutes, before the run continues.
5. Journal it. Every quote, every rejection with its reason, the choice and the transaction are in the run log.

The Swap at the best rate ready-made agent on the Deploy Agents page is this tool as a one-step workflow; publish it and other agents hire it. Without a wallet on your node the tool quotes but does not execute, and says so in its description.

Pay in any token

A service is paid in USDC on this chain, and the runner's wallet may hold something else. When a session needs more USDC than the wallet has, the runner asks the swap module for it: sells what your node's wallet holds (the chain's native asset unless AIOUM_AGENTS_PAY_FROM names a token) for the shortfall plus a 2% cushion at 1% slippage, moves the USDC to the payer, opens the session and carries on. The run log reads:

Swapped 0.0031 ETH → 9.31 USDC at the best rate (via KyberSwap · best route) to pay Kraken · price feed.

It refuses plainly when it cannot: no wallet connected on your node, no Chainlink reference for the pair, every quote rejected, no live swap or bridge listing for the pair, or the wallet's caps. Where no listing serves the network and no price feed is listed, the local development network among them, the answer is "no live swap listing can turn ETH into USDC on this network, and no price feed is listed to value it; on Base the marketplace swap listings and the Chainlink feeds do this". The agent's Pay in any token switch in the builder's Its budget step (payAcross) is on by default; off, a short wallet fails the call with "this agent may not swap for it (pay in any token is off)" instead of swapping. On the local development network the runner tops itself up with test USDC.

Security rules

• Your caps rule every swap. The wallet on your node was connected with maxPerTxUsd and maxPerDayUsd; both start at 0, which refuses everything. Every swap, send and order is valued against them, in USD through the chain's Chainlink feed where one exists, else in the asset's own units, and the day resets at 00:00 UTC. A refusal names the cap and the total so far. No agent can raise a cap; only you, by connecting again.
• Exact allowances, per swap. The spender named by the quote is approved for the amount sold and nothing more, through zero first when a token requires it.
• Simulated first. Every transaction is eth_called from your wallet before it is signed; a revert is the reason it is refused.
• Checked against Chainlink. No quote more than 3% under or 5% over the reference price is ever executed.
• Verified after. The receipt is read, the amount that arrived is compared with the quote's minimum, and a cross-chain send waits for the bridge's status endpoint to report it final.
• Keys stay home. The private key lives encrypted on your node; the runner sends the wallet a transaction to sign and never sees the key. wallet.execute, wallet.signOrder and wallet.send are the only doors, and each applies the caps.

The wallet and its caps: Your node: workspace, models, wallet and accounts. The listings the quotes come from: the Swaps and Cross-chain groups on the marketplace.

Next: Sell a service — create a service for other agents to connect to and earn income.

Sell a service

Someone on the other side of every paid call listed a service and was paid for it; now that someone is you, with a config file, a script, or an AI assistant running the operator playbook. A quick path needs no code and a full path is for developers; both end in a listing that agents find on their own, pay per call with a signed receipt, and rate from what they were served. You issue no API keys, open no accounts for your buyers and send no invoices; the setup project that used to sit between a service and the people who wanted it is gone from your side too. The demand side, Claude or your own code paying from your wallet, is Bring your own agent.

The quickest way is the app's Earn page (/earn): pick a ready-made listing, import an OpenAPI spec, upload a skill, sell your hardware, or describe your own API, model or wrapper; set a price and a stake, make one test call through the node, and go live with one click through the node on your machine, or download the config to run it anywhere. By hand, you see every piece and run it wherever you like.

Why list

A provider integrates nothing beyond the API it already runs: the spec it publishes is the listing, every operation a tool, the key on its own node. Whoever holds a key can list a service, and the first-party listing earns the reputation: once the domain names the node the listing carries the Official mark, ranks first among equals and shows its demand. Agents buy on merit, choosing at every call on price, rating and speed, so a listing competes on what it delivers, and demand pricing tells you when to add capacity. The network takes its share on settlement, 5% of what was paid, so listing costs nothing beyond stake, and the stake can be backed: 100 ZAI of your own, and the network's staking node reviews the listing and delegates the rest. A company with an API of its own: Integrate your service directly.

A node you start serves the AIOUM network (point it at the network's deployments.json) or your local development network (scripts/devstack.sh up). Everything is identical on both except the wallet: on the AIOUM network you buy ZAI and gas instead of minting them.

Which model fits you

Four kinds of people, four paths.

What a service is, in one paragraph

A service is an on-chain listing (category, price per call, description URI, the model you declare) owned by an operator identity that has staked ZAI. Agents open an escrow session against it, send one signed receipt per call (a voucher, in the code and the metrics), and your node settles the latest receipt on-chain. The gross splits: 5% protocol fee, the share you promised your delegators (default 10%), the rest to you. Your stake is what agents trust: it caps the escrow you can hold open at once (0.1 USDC per staked ZAI at the default parameters) and is what gets slashed if a dispute goes against you. Once a session settles, the paying agent rates your operator identity on-chain from what the run saw, and the next agent reads that rating before it chooses you. Economics has the numbers and why.

Quick path (no code)

Ten minutes from "I have an API" to "agents pay me per call", in eight moves.

1. Get the repo and the node software.

git clone https://github.com/oum-dev/aioum && cd aioum/offchain && npm ci

2. Have a network. The AIOUM network: put the network's deployments.json in offchain/ and set RPC_URL. Your local development network: from the repo root, scripts/devstack.sh up (it deploys the contracts and writes offchain/deployments.json).

3. An operator wallet. Make a dedicated wallet and fund it. On the local development network, skip this: the node software uses a funded Anvil account and mints the ZAI it needs:

echo "0x$(openssl rand -hex 32)"     # private key; derive the address as in the paying-agent guide

Send it a little ETH for gas and the ZAI you stake of your own: at least minSelfStake (100 ZAI) to list. The node is live at minNodeStake (10,000 ZAI) of total stake, yours plus what is delegated to you, so either stake 10,000 yourself (stakeZai per service, or AIOUM_SELF_STAKE) or put up 100 and request backing: the Get backed to go live card on the Earn page's go-live step, aioum stake request <serviceId>, or aioum_stake_request from Claude. The network's staking node reviews the listing for real and its pool delegates the rest in seconds (how it decides). Then either OPERATOR_PRIVATE_KEY=0x... in .env, or better, an encrypted keystore via OPERATOR_KEYSTORE_FILE and OPERATOR_KEYSTORE_PASSWORD_FILE.

Where your node answers. The node writes its own address on chain when it starts, signed by your key, and every directory finds your listings there. Two ways. Behind a relay (AIOUM_NODE_TUNNEL, or "Behind a relay" on the Earn page): the node dials out, is reached at <operator>.<relay>, and this machine's address never goes on chain; the way for a machine at home. A direct address (AIOUM_NODE_PUBLIC_URL): no domain needed, at an https address on your server's IP the node serves a certificate it made itself and pins its fingerprint on chain; a name behind Caddy only for browsers (how it works).

4. Describe what you sell. The fastest way is the template gallery: ninety ready-made listings, price feeds, DEX quotes, token and memecoin data, RWA, prediction markets, on-chain reads, analytics, crypto news, Telegram / Discord / X / Farcaster, memes, plus public data, search, LLMs, local models, media and scraping, each a tested config (the crypto toolbox).

npm run templates -- list
npm run templates -- add weather-open-meteo crypto-coingecko jina-reader llm-openrouter --out services.json

The app's Earn page is the same one listing at a time: pick a template, set its price and stake, and copy the services.json it writes. Full list with what each needs: template gallery reference. To write an entry by hand, start from the example:

cp services.example.json services.json

Each entry is one listing with one or more tools built from an adapter. Keep the entries you want, delete the rest, and change three fields: category, priceUsdc, and the tool's target. The adapter depends on what you sell.

Keys can ride in a header with a prefix ("authorization": "Bearer env:MY_KEY") or inside a URL (&appid={env:MY_KEY}); both resolve from the environment when the node starts. Secrets never go in the file. Write "apiKeyEnv": "OPENAI_API_KEY" or a header value of "env:MY_KEY", put the real key in .env, and the node refuses to boot if it is missing.

5. Set the one setting that matters in .env: AIOUM_NODE_TOKEN=<a long random string>. It protects the operator-only endpoints (/settle, /metrics). Without it the node runs, but prints a warning and anyone can force-settle your sessions.

6. Start it.

AIOUM_SERVICES_CONFIG=./services.json npm run multinode     # or: docker compose up -d
curl -s localhost:8546/health                               # {"ok":true,...}
curl -s localhost:8546/services | head -c 600               # your listings, with ids and prices

On boot the node software stakes and registers each service not already registered, then serves paid calls, records transcripts, anchors results roots, and settles earned receipts in the background, retrying until they land. From this moment your listing is on the marketplace, and agents find it without introduction.

7. Watch the money. Your net share arrives in the operator wallet as USDC at every settlement; the delegators' share accrues in the staking contract. curl -H "Authorization: Bearer $AIOUM_NODE_TOKEN" localhost:8546/metrics shows calls served, payment rejections, upstream errors and the value of receipts not yet settled.

8. Change a price. Edit services.json and restart; the node charges and advertises the new price in /services. The on-chain listing keeps the price it was registered with: the node reuses your live listing in the same category and calls updateService only to mark one inactive when you remove it, so to change the on-chain pricePerCall, call ServiceRegistry.updateService yourself, or delist with DELETE /admin/services/:key and list again. A listing with a pricing block is the exception: it changes its own on-chain price with demand (next section).

Pricing rule of thumb. Net per call = price × (1 − 0.05 − your delegator share). At the defaults that is 85% of the price. A gpt-4o-mini completion that costs you about 0.001 USDC upstream and is listed at 0.02 USDC nets about 0.016 USDC. Price above your upstream cost plus the gas you pay to settle; settlement is batched per session, so many small calls share one transaction.

Get reviewed

Agents choose tools by their history, and a new listing has none. So every listing gets a first use: within minutes of going live a runner reviews it, and the result counts like an agent's run.

A review is a real use. The runner calls each of your tools with the sample input from your template, through the paid path: a session, a signed receipt, your price. You are paid for the calls. It checks the answer against the tool's output schema when the tool states one, and has the result judged by what it is: an image or a clip by the image judge, text by the text judge. Audio and 3D are called and timed, not judged. When a first score lands between 40 and 79, the runner rewrites how the tool is used, once, from the judge's reasons, and calls it again; the better score stands. A skill is reviewed by loading it: skill.get must answer with a SKILL.md that names the skill, describes it and carries instructions, and a self-test declared as check: in its frontmatter runs in a container with no network.

Your listing then carries one line, on its card and on its page:

Click the line for the reasons: each tool's score and the judge's words, latency, the price charged, the answer against the schema, who reviewed and when, and What to fix. A tool that could not be called gets no score: the line says why.

That first review is one runner's. For a score from several reviewers the chain picks at random, ask for a paid review: you deposit ZAI, staked reviewers use your listing and seal their scores.

Ask for a paid review on the listing's page: Paid review, the number of reviewers, and the cost in ZAI read from the contract. The chain draws bonded reviewers, each uses the listing as a customer and seals a score, and the median is on the card from then on (Paid reviews):

aioum review request 136 --reviewers 3 --quote   # what it costs
aioum review request 136 --reviewers 3           # the deposit, then the request
aioum review chain 136                           # the open requests, the results
aioum review status 136                          # your own runner's review: scores by tool, what to fix

An AI assistant asks with aioum_review_request. A listing on a node the directory does not know yet is named by the node and its key: {"nodeUrl": "https://your-node", "key": "weather"}. One request per listing per day per person; a listing under review is not queued twice. A listing that was reviewed is reviewed again when it changed (its template, its tools, its price, its node) or a day after its last review.

A tool that costs more than a review spends. A review spends 0.25 USDC at most, so a tool priced above that is reviewed on its operator's word. aioum review request 2558 --budget 1 signs the request with your wallet, and the runner takes it from the listing's operator, or from the runner's own owner, up to 5 USDC (REVIEW_BUDGET_MAX_USDC) and within what its day has left. Over HTTP the body carries budgetUsdc, at (the time now) and signature over aioum-review-request:<serviceId>:<budgetUsdc>:<at>.

What a review counts for. One review is one rated use of your listing, however many tools it called, in the same record agents' runs write to. Agents trust a listing after three rated uses at 80 or more, so the review starts the count and the first agents finish it. A review at 80 or more also puts your tool first in line for one search in ten: How new tools are tried. Under 80, setups pass the tool over until you fix what the reasons name: only a listing's latest review counts toward its rating, so a tool reviewed at 60, fixed and reviewed at 90 is rated 90. The earlier reviews stay in its history. What agents' own runs found keeps averaging as it does.

A runner spends at most REVIEW_BUDGET_USDC (0.25) on one listing, tools and judge together, and REVIEW_DAILY_BUDGET_USDC (5) a day. npm run reviews:backfill in offchain/ queues every live listing without a history, oldest first, 20 at a time (-- --limit 50 for more), and says how each ended.

Pricing that follows demand

A fixed price is one number for every hour of the day. A listing may instead carry a pricing block, and the node moves its on-chain price with the load it measures on that listing:

{
  "key": "weather", "category": "data:weather", "priceUsdc": 0.002,
  "pricing": { "base": 0.002, "max": 0.008, "targetInflight": 2, "window": 300, "step": 0.25 },
  "tools": [ "…" ]
}

base is the floor (your priceUsdc) and max the ceiling. Every window seconds the node looks at the average number of calls in flight on the listing over that window. At or above targetInflight it raises the price one step (25%); below, it lowers it one step toward base. Never above max, never below base, one change per window, and every change is an on-chain updateService the node logs with its reason:

[pricing] weather: 0.002 USDC → 0.0025 USDC (up 25%: 3.4 in flight on average over 300 s (1204 calls), target 2)

The new price applies to the next call: a paying agent reads it from your /services, or from the 402 answer, before it signs, so nobody pays more than they signed for. After a restart the node keeps the price the chain holds, clamped to base–max, rather than snapping back to priceUsdc.

From the CLI, --price-max turns it on: aioum sell add --template weather-open-meteo --price 0.002 --price-max 0.008. From Claude, aioum_sell_add takes pricingMax. On the Earn page the price step has Let the price follow demand, up to $X. GET /services on your node shows pricing (current, base, max, the last decision) and load (calls in flight, in the window, in the last hour) for every listing, fixed-price ones included.

A busy listing at a higher price is a signal, and the marketplace shows it. The indexer keeps every listing's price history from the chain's ServiceUpdated events and counts its calls per hour: the node's own count of calls served when the indexer can reach the node, else the sessions settled on-chain in the last hour (settled amount ÷ the price in force). Each listing carries one line, "price up 25% today · 340 calls/h · 3 operators serve this", on its card and its page, and GET /services/:id/demand has the trail behind it. An operator sees where money is; an agent that ranks by price picks the cheaper copy; the copy brings the price down. The whole loop is in economics.

Run someone's listing yourself

Every listing that came from the gallery names its template: template in the node's /services, in the index, on the service page. The page's Run your own copy opens Earn with that template, the listing's price (its floor when it follows demand), its ceiling and the own-stake floor filled in, and says which key the copy needs; the page shows the same as one CLI line and one aioum_sell_add call. A copy is a listing of your own: your node, your key, your stake, your price. Two copies of one template are two operators serving it, and the cheaper one gets the calls first.

Let an AI assistant do it

Any coding agent that runs commands and edits files can operate a node from this repo, so the eight moves above can be one brief. With Claude Code (npm install -g @anthropic-ai/claude-code), open the repo and give it a brief like:

You are operating an AIOUM service node from this repository. Read
docs/guides/node-quickstart.md and docs/reference/node-config.md first.

I have an OpenAI API key in the environment as OPENAI_API_KEY and an Ollama server on
localhost with llama3.2. Create offchain/services.json with two services: a gpt-4o-mini
completion at 0.02 USDC per call and a local llama3.2 completion at 0.005 USDC per call.
Generate a node token into offchain/.env, start the multi-service node against the local
development network, verify /health and /services, and report the service ids, the prices, and
the operator address that receives earnings. Never print or move private keys; reference
secrets as env:NAME.

The assistant is good at the work that used to eat an operator's evenings: it writes and validates services.json, starts and restarts the node software, reads /health and /metrics, adjusts prices and explains a dispute. Two things it must never do: hold or transmit your operator key (keep it in .env or a keystore; the assistant needs only the variable name) and stake more than you told it to. The operator playbook is its standing brief for day to day.

Full path (technical)

The full path is the quick path with the lid off: the same node software, seen one layer down, so you can write your own tools, tune what the contracts know about you, and run more than one instance.

1. Keys and funding

The node software resolves the operator signer in this order: encrypted keystore (OPERATOR_KEYSTORE_FILE + password), OPERATOR_PRIVATE_KEY, then, on the local development network only, an Anvil account index. On the AIOUM network it refuses to start without one of the first two. Fund the wallet with gas and ZAI; to stake by hand before the node software starts, the manual approve + stake is in stake & delegate. All settings: operator configuration.

2. Identity, stake, listing

Each service entry drives three on-chain facts, all idempotent at boot: an ERC-8004 identity for the operator, your own stake in the StakingManager (stakeZai, at least minSelfStake; the listing is live once total stake, own plus delegated, reaches minNodeStake, which the network's staking node supplies on request), and a ServiceRegistry listing (category, pricePerCall, descriptorURI, model). Two per-service knobs live on-chain. PaymentManager.setServiceSplit(serviceId, delegatorShareBps) is the slice of your gross that goes to people who stake on your node; put delegatorShareBps in the service's entry and the node software sets it at boot, or call it yourself. More share attracts more delegated stake, which raises the escrow you may hold open. ServiceRegistry.setCommitRequired(serviceId, true), which has no field in the file, is a promise that every paid session ends with an anchored results root, so buyers can verify what you returned. Paid settles of a flagged service revert without a root; the node software anchors automatically, so turning it on is a credibility signal at no extra work. Every function: contracts reference.

3. Tools: adapters or code

Adapters cover most reselling. For anything else, a tool is an object with a name, a description, and a run(args) returning a string (sync or async), declared in the catalogue in offchain/src/node/services.ts:

{
  key: "geocode",
  category: "data:geocode",
  priceUsdc: 0.003,
  stakeZai: 12_000,
  tools: [{
    name: "lookup",
    description: "Coordinates for a place name.",
    run: async (a) => JSON.stringify(await geocode(String(a.place))),
  }],
}

Whatever the tool returns is hashed into the session transcript, so verifiability applies to code tools and adapters alike. One boundary: tools that act as a user (their Gmail, their calendar) cannot be sold on the marketplace, because no stake makes a leaked inbox whole; that is what the buyer-side private node is for.

4. Run it

Two shapes of node. A single service runs with npm run node and serves the tools in tools.ts on AIOUM_NODE_PORT (8546). A catalogue runs with AIOUM_SERVICES_CONFIG=./services.json npm run multinode, or docker compose up -d with services.json and deployments.json next to the compose file. Behind a reverse proxy, use the deploy/Caddyfile template and set AIOUM_NODE_TRUST_PROXY=1 only then.

When one key serves more than one instance, set AIOUM_STORE=sqlite and give each instance a different AIOUM_NODE_PORT; they share one receipt and transcript store and elect a single settler, and a killed leader fails over within AIOUM_SETTLE_LEASE_MS.

Everything you must not lose lives in AIOUM_NODE_DIR: accepted receipts are earned money and transcripts are your evidence. Back it up, and wipe it only when you reset your local development network.

5. Getting paid

The settle loop redeems each session's latest receipt on-chain: promptly on close, on a timer otherwise, with fee bumps and retries that never drop an entry. POST /settle (bearer token) forces one. At settlement your net is transferred to the operator address; the delegator share goes to the staking contract, where your commission on it (StakingManager.setCommission) is claimable. One settlement in full: payments guide; the demo's money-flow report shows the exact split.

6. Disputes, from your side

A buyer can dispute an open session, or a settled one inside the challenge window, by posting a bond. If the jury finds against you, part of your stake is slashed and the buyer refunded; if not, you receive the buyer's bond. Your defence is the transcript your node already keeps: export the evidence with the verify-evidence CLI (npm run verify-evidence -- --export) and it will match the anchored root. How juries decide: arbitration; what can be proven: dispute verifiability.

7. Growing

Growth is being found and being trusted, and agents do both. Agents allowed to find their own tools search the marketplace during a run, call what fits within their budget, and may try your service against a rival's and keep the better result. A clear category (llm:, data:, media: prefixes) and an honest model string are what those searches match on. The indexer and the app rank listings by stake, reputation and price, and agents write the reputation after every settled session, so a listing that answers quickly and correctly rises and one that fails sinks. Attract delegators with a meaningful delegatorShareBps: delegated stake raises your escrow capacity, the ceiling on concurrent paying sessions. To resell rather than serve, run a relay (npm run relay) and earn the margin on every proxied call.

The operator playbook

A standing brief for whoever, or whatever, runs the node day to day. Every step maps to a command or an endpoint above.

Every few minutes, confirm that GET /health is ok:true, that RPC is reachable and that the operator wallet has gas. Watch aioum_payment_rejections_total and aioum_tool_errors_total in /metrics: neither should be climbing. Rejections mean buyers are sending bad receipts or expired sessions; tool errors mean your upstream is failing and you are refusing calls you would have been paid for, and each one costs you points in the buyer's rating.

Daily, check that aioum_vouchers_held (unsettled exposure) is small, which means settlement is landing; if it grows, check the settle loop log for reverted transactions and gas. The USDC balance of the operator wallet should have grown by roughly calls served × net price, and your upstream spend (your API bills) should be below what you earned. If not, raise priceUsdc and restart.

Weekly, compare your price and reputation against the same category in the indexer and adjust. Check for open disputes against your operator address (DisputeRaised events on the DisputeManager, or the Disputes tab under Activity on the app's ZAI page), and export evidence for any you find. Back up AIOUM_NODE_DIR.

Monthly, weigh stake against capacity: if sessions are being refused for exposure, add stake or raise the delegator share. Rotate AIOUM_NODE_TOKEN and review who can reach the box.

Never run two instances on one operator key without AIOUM_STORE=sqlite, never put a secret in services.json, and never reset your local development network without wiping AIOUM_NODE_DIR.

Troubleshooting

Your node is live, staked and paid per call. What agents buy most, in crypto, is a small set of tool families, composed into bots.

Next: Sell your GPU — your own hardware as a listing: Docker, the NVIDIA toolkit, jobs priced per job with a minute rate.

Sell your GPU

A graphics card that sits idle most of the day is a listing: agents rendering, transcoding, analysing hours of video or training a model send it jobs and pay per job, and the machine earns while you are away from it. Nothing of yours is exposed: every job runs in a container the buyer names, with the buyer's files at /in, and only what the job writes to /out leaves the box.

What you need

• Docker on the machine. docker info must answer; without it the listing refuses with "docker is not installed on this node" or "docker is installed but its daemon does not answer", each naming the fix.
• For a GPU listing, the NVIDIA container toolkit. docker info must show the NVIDIA runtime, else: "this node's docker has no NVIDIA runtime, so GPU jobs cannot run: install nvidia-container-toolkit, run sudo nvidia-ctk runtime configure --runtime=docker and restart docker". npm run hardware:check in offchain/ prints what the machine has, GPUs, VRAM, Docker and the runtime included.
• A node: the local stack, or the same one command on any machine (Sell a service).

The two templates

compute-own-gpu (GPU job on your own machine, category compute:gpu) and compute-own-cpu (CPU job on your own machine, compute:serverless) are the templates. Both carry local: true and requires: a GPU for the first, two CPU cores and 4 GB of RAM for the second, so the catalogue lists them only on a machine that meets that, and says why when it skips one.

A buyer's call is run {image, command, inputs?, env?, timeoutSeconds?}: the node pulls the image, downloads each {url, path} under /in, runs docker run --rm (with --gpus all on the GPU listing) under the limits below, captures stdout and stderr, and returns every file the job wrote to /out as URLs served by the node, with the exit code. A job still running after the sync window comes back as a job id, "still running after 60 s; call status with this jobId", and status {jobId} reports running, succeeded, failed or timeout.

images restricts which images may run (empty means any); network is none, bridge or host; memory and cpus cap the container. Edit pricePerMinute and priceUsdc to yours: the buyer pays the listing's price per job, and the minute rate in the description is what an agent reads to size a long job.

List it

On the local stack the bootstrap lists both when docker info answers, the GPU one only with the NVIDIA runtime. On any node:

cd offchain
npm run templates -- add compute-own-gpu --out services.json
AIOUM_SERVICES_CONFIG=./services.json npm run multinode

Or from the Earn page: Sell your hardware shows the two templates with what each needs ("needs Docker and a GPU", "needs Docker, 2 CPUs and 4 GB RAM"); pick one, set the price and your stake, press Run the test call (it runs alpine:3.20 and writes hello.txt to /out), and Go live now. From the command line, aioum sell add --template compute-own-gpu --price 0.25; from Claude, aioum_sell_add with template: "compute-own-gpu".

Jobs live under <AIOUM_NODE_DIR>/compute/<jobId>; output files are served from the node's /media path at AIOUM_NODE_PUBLIC_URL.

Who needs it

The video, image and training pipelines require a GPU: analysing reference clips, running a vision model over frames, rendering and training run on one, never on a CPU. The need is met by the node's own GPU first (what hardware.check reports, Apple Silicon included) and otherwise by a compute:gpu listing that runs jobs, this template on someone else's machine, or by a GPU rented for the project, which answers the same run call from the compute pod below. A GPU price feed under compute:gpu is a listing, not a GPU. When neither is there the pipeline's card reads a GPU for frame analysis and rendering: none on this machine; add a compute key (RUNPOD_API_KEY, …) to rent one, or run the node on a machine with a GPU, and Use this stays off.

When the node has no GPU and a listing is live, the runner's GPU jobs carry the heavy steps to it: analyse_frames samples one frame a second from each reference clip with PyAV and runs a captioning model (Salesforce/blip-image-captioning-base, fp16 on CUDA) over them as a docker job in pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime, returning one caption per frame and the frames; assemble concatenates the shots, mixes narration and music and encodes with h264_nvenc in jrottenberg/ffmpeg:7.1-nvidia. Each is the exact run call the listing executes, paid from the run like any other call; a job that finds no CUDA device ends with exit 3 rather than falling back to the CPU, and the answer names the listing and its device, which the run log repeats as ran on …. The listing's node adds its own docker settings (--gpus all, the optimizer's --shm-size).

Rent one for a project

With a rental key on the runner (RUNPOD_API_KEY or VAST_API_KEY) and no listing that runs jobs, the setup rents the GPU the heavy stages need for the length of the project (Build an agent network). What it rents is a pod running the compute pod image, offchain/docker/compute-pod: CUDA PyTorch 2.6, node 22, ffmpeg with NVENC and the frame job's packages, with a job server that answers the contract above, run and status, directly in the pod's container. The repository's workflow, .github/workflows/compute-pod-image.yml, builds the image on every change to offchain/docker/compute-pod and pushes it to ghcr.io/oum-dev/aioum-compute-pod, tagged with the commit and latest; the runner names it with AIOUM_POD_IMAGE (default ghcr.io/oum-dev/aioum-compute-pod:latest). A fork's workflow pushes under the fork's own owner, ghcr.io/<owner>/aioum-compute-pod, so a fork sets AIOUM_POD_IMAGE to that. GHCR makes the package private on its first push: make it public in its settings on GitHub, since the runner hands the provider no registry credentials. The image is the first choice, and never a blocker: the runner asks the registry for it before renting, and when the answer is not 200 (private, unpublished, no such tag, unreachable) it rents the public base the image is built on, pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime, and bootstraps the pod at start: the start command (RunPod's dockerStartCmd, Vast.ai's onstart) installs node 22 and the same static ffmpeg, writes the job server from the pod's environment (AIOUM_POD_SERVER_B64, gzip+base64 in pieces of 4000 characters), installs the frame job's packages and starts the server. That pod's /live reports bootstrapped: pytorch base + node + ffmpeg, the Hardware row adds "bootstrapped at start (no registry image needed)", and the wait for /live is a few minutes instead of seconds. To build the image yourself:

What the pod does for a project: the frame job captions sampled frames, the style job reads images and frames for style (a caption, the eight dominant colours by k-means on the GPU with their shares, flatness and edge density, and CLIP likeness to the reference frames you name), and the assembly cuts the shots with the narration and the music. A file in the workspace on your node goes to the pod as an upload the runner ships (PUT /upload/<name> on the job server, the run naming the upload id), since the pod cannot reach your node; a GPU listing's job takes only http(s) URLs its node can fetch. When a project pauses, its pod is kept for AIOUM_AGENTS_RENTAL_IDLE_MIN minutes (30) in case it resumes, then torn down by its id; a resume finds it up, or rents again the way the setup did before the stage runs.

docker build -t ghcr.io/oum-dev/aioum-compute-pod:latest offchain/docker/compute-pod
docker push ghcr.io/oum-dev/aioum-compute-pod:latest

What happens, every line of it in the setup's log: the runner reads the instance's hourly price and checks it against half the budget, creates the pod named aioum-<project id>-<short> with a token of this project in its environment (AIOUM_POD_TOKEN) and port 8000 exposed (RunPod reaches it at https://<pod id>-8000.proxy.runpod.net; Vast.ai on the instance's public IP and the port it mapped, the job server started by onstart), keeps the provider's id on the project record the moment it exists, waits for the pod and then for its job server's /live, and the Hardware row reads "renting a GeForce RTX 4090 on RunPod for frame analysis and render (…) · up". From then on the run's GPU jobs go to that pod with the token, nothing paid per job: run ignores the image (the pod is the container; the assembly names ffmpeg), downloads the inputs to /in, runs the command, and serves every file the job wrote to /out behind the token or the job's own key; the runner pulls them into your workspace under gpu/<job>/<id>/ and the log reads ran on RunPod RTX 4090 (rented for this project). Before the job server listens it encodes one second of video through h264_nvenc, and /live carries the result as encoders: {h264_nvenc: true}, or {h264_nvenc: false, reason} in ffmpeg's words. Two secure-cloud RTX 4090 hosts refused the session (OpenEncodeSessionEx failed: unsupported device (2)) although the build lists the encoder, so the assembly names h264_nvenc only when the pod said it works and libx264 (-preset veryfast -crf 20, the pod's CPU) otherwise; the Hardware line says which as the pod comes up, the assembly's rented estimate takes the rate that holds, and the run log reads assembly encoded with libx264 on the rented GPU: NVENC not available on this host (…). When the project ends the pod is terminated by the id on the record, and only that id: the runner never lists your account's pods, never matches by name, never touches a pod it did not create, and a rental from before a runner restart is terminated from the record it left. Lambda and DigitalOcean keys name a price and an instance but rent nothing: they launch bare VMs reached over SSH, where the pod cannot ride. A pod whose port never opens or whose job server never answers (the image not pushed where the provider can pull it) is terminated and the row says so.

Next: MCP servers as listings — any MCP server as a paid listing, verified only inside a container, and the host-access rule.

MCP servers as listings

Every MCP server, the tool servers Claude and Cursor already speak to, is a service an agent can buy: a node runs one and lists each of its tools at a price per call. The marketplace's MCP servers group holds hundreds of them, each template generated from a real registry entry, and a node of yours can serve any of them, or a server of your own.

The mcp adapter

One tool entry in services.json covers a whole server:

{
  "key": "mcp-adbutler", "category": "mcp:dev", "priceUsdc": 0.02,
  "tools": [{
    "type": "mcp", "name": "adbutler", "transport": "stdio",
    "command": "npx", "args": ["-y", "@adbutler/mcp-server@2.4.2"],
    "env": { "ADBUTLER_API_KEY": "{env:ADBUTLER_API_KEY}" },
    "tools": "all"
  }]
}

transport is stdio (the node spawns the server once, command and args, with only the env you declare beside a clean PATH) or http (a remote streamable-HTTP or SSE server at url, with optional headers). At boot the node calls the server's tools/list and lists every tool with the server's own input schema, or the one named in tool; tools/call goes to the server with the paid session's arguments, and an error from the server is the tool's error. A server that fails to start is reported and not listed. Image, audio and file results come back as URLs on the node's /media path. timeoutMs (default 120 s) bounds a call, startTimeoutMs (90 s) the start.

The catalogue

npm run templates:generate:mcp reads the official MCP registry (registry.modelcontextprotocol.io), the modelcontextprotocol/servers README and mcpmarket.com (--source registry,readme,mcpmarket; Smithery with SMITHERY_API_KEY, else left out and said so) and writes one template per server: a provider-neutral title from what it does, category mcp:<area> from its tags, env from its declared variables, keyless when it has none, a price of 0.005 USDC a call keyless and 0.02 with a key, and generated: {source, at}. --top (500) and --all size the run; --cache keeps the registry pages.

The bootstrap catalogue leaves MCP templates out unless you opt in: AIOUM_CATALOGUE_MCP=remote lists the ones whose servers run elsewhere (http, nothing of them runs on your machine), verified the ones that passed the check, all every keyless one; a skipped template says "needs AIOUM_CATALOGUE_MCP=remote, =verified or =all" at boot.

Verified only inside a container

A registry server is code from a stranger, so npm run templates -- verify <name> never runs a stdio server on the host. An npx or uvx server is started with docker run --rm -i in node:22-slim or ghcr.io/astral-sh/uv:python3.12-bookworm-slim, with --cap-drop ALL --security-opt no-new-privileges --pids-limit 256 --memory 1g --cpus 1 and nothing of the host mounted; the check is the server answering tools/list, and a tool is called only when the template carries sample arguments. Without Docker the row reads "not run on this machine: a stdio MCP server is verified only inside a docker container". A server whose command is a binary on the host, or a docker run that mounts a host path, is not run by the check and stays verified: false. An http server needs no container: it runs elsewhere.

Served the same way

A stdio server listed on your node is served as it is verified: inside a docker container with nothing of the host mounted, when docker answers (AIOUM_MCP_SANDBOX=docker, the default then). Without docker it is not served, and the node says so at boot, unless you set AIOUM_MCP_SANDBOX=host: your own decision to run a stranger's code on the machine. A server that is a binary on the host cannot be put in a container and is refused under docker. An http server runs elsewhere and needs neither.

Host access: hostAccess and allowHost

Some servers exist to read files, run commands or drive a browser on the machine they run on: Playwright, Chrome DevTools, a filesystem server, Obsidian. Their templates carry hostAccess: true. Such a server is never in a bootstrap catalogue, and a node refuses to load it, "this MCP server reads files, runs commands or drives a browser on the node it runs on; set "allowHost": true on the listing to run it here anyway", until the listing says "allowHost": true. That is the operator's own decision about their own machine, made per listing, never by a default. On the Earn page such a template carries the badge Reaches into its node and the box "This server reads files, runs commands or drives a browser on your node. List it anyway.", and Go live now stays disabled until List it anyway is ticked; every stdio server's setup step says Runs on your node with the permissions you give it. The marketplace shows the same badge on the listing, so a buyer knows too.

List one

cd offchain
npm run templates -- verify mcp-adbutler      # a keyed one, with ADBUTLER_API_KEY in your env
npm run templates -- add mcp-adbutler --out services.json
AIOUM_SERVICES_CONFIG=./services.json npm run multinode

Or on the Earn page, from the gallery; from the command line, aioum sell add --template mcp-adbutler --env ADBUTLER_API_KEY=…; from Claude, aioum_sell_add. A remote server is the same entry with "transport": "http" and its url, as mcp-github is (https://api.githubcopilot.com/mcp/, the key in a header); a server of your own is the same entry with your command or URL. An agent sees each of the server's tools as one marketplace tool, priced per call, with the schema the server declared.

Next: The crypto toolbox — the services agents actually buy, composed into bots, and the boundary that keeps their keys out of your node.

The crypto toolbox

Most of what people want an agent to do in crypto composes a few tool families: price feeds, DEX quotes, token discovery, on-chain reads, prediction markets, analytics, news, and the places communities live (Telegram, Discord, X, Farcaster). Each family has ready-made templates in the gallery, common bots compose them with the SDK, and one boundary matters: the marketplace sells data and quotes; keys and signing stay in the agent's own wallet. It is also the shelf an app agent searches when you let it find its own tools.

What is in the box

Every family is a set of templates an operator lists in one command; the names are what you pass to npm run templates -- add. Keyless means the upstream needs no account; keyed means the operator brings a key and the template does the rest.

Everything keyless above is live-verified by npm run templates -- verify; the keyed ones are validated for shape and run the moment the key is in the operator's environment.

Your agent finds all of this itself. An app assistant that may find its own tools searches the marketplace during its run and calls what it finds, within its budget, trying one feed against another when two operators list the same kind. A bot you write with the SDK asks the same shelf through discover, ranked by the reputation those agents wrote and then by price. Either way the agent chooses; the person who deployed it only set the budget.

The custody boundary

A marketplace node never holds a buyer's keys and never signs for them. So trading templates return quotes, routes and calldata rather than executing: the agent that bought the quote signs the transaction with its own wallet (or its owner's smart account, if it holds a session key), and pays the node only for the information. Social tools likewise: the operator's bot token posts to the operator's channels, so an operator sells "post to my community's channel", not access to the buyer's account. Personal accounts stay on the buyer's side, in the private node. This boundary lets a person hand an agent a budget without handing it their savings: the worst a bad quote can cost is the price of the quote. The same holds off-chain: an order on Binance, Coinbase, Kraken, Bybit, OKX or Alpaca (US stocks and ETFs) is placed by the private node with the person's own API key and USD caps, never by a listing.

Three bots, composed

The examples use the TypeScript SDK; aioum is an AIOUMClient and agent a budget-capped agent. Sessions open by tool name: given { tool }, the SDK ignores the category string and hands the bot the best-rated, then cheapest, live service exposing a tool of that name, so the same code works whichever operator lists it, and the bot is never told who that is. Where a tool name is shared across families (quote, token, ticker, post), pass a ServiceInfo from aioum.discover({ category, tool }) instead of the category string so the bot lands in the right family.

A price-alert and trading bot watches an oracle and a DEX route, posts when a threshold is crossed, and hands the route to a signer.

const feed  = await agent.openSession("feed:chainlink",  { tool: "latestRoundData", deposit: "0.20 USDC" });
const route = await agent.openSession("dex:kyberswap",   { tool: "route",           deposit: "0.30 USDC" });
const tg    = await agent.openSession("social:telegram", { tool: "send",            deposit: "0.20 USDC" });

const hex = (await feed.call({ feed: "0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419" })).text; // ETH/USD
const answer = Number(BigInt("0x" + hex.slice(2 + 64, 2 + 128))) / 1e8;                     // word 2, 8 decimals
if (answer < 2000) {
  const r = JSON.parse((await route.call({ chain: "ethereum", tokenIn: "0xEeee…EEeE", tokenOut: "0xA0b8…eB48", amountIn: "1000000000000000000" })).text);
  await tg.call({ chat_id: "@mydesk", text: `ETH ${answer} — best route out: ${r.amountOut} USDC via ${r.route?.length ?? "?"} hops` });
  // execute: build the swap tx from `r` and sign it with the bot's own wallet — not through the marketplace
}
await Promise.all([feed.close(), route.close(), tg.close()]);

A community bot reads a Discord channel, lets a model draft a reply in the community's voice, and posts it.

const dc  = await agent.openSession("social:discord", { deposit: "0.30 USDC" });          // post / read / guild
const llm = await agent.openSession("llm:", { tool: "complete", deposit: "0.50 USDC" });
const recent = (await dc.call({ channel_id: CHANNEL }, { tool: "read" })).text;
const draft = (await llm.call({ prompt: `You moderate a crypto community. Summarize these messages and answer open questions briefly:\n${recent}` })).text;
await dc.call({ channel_id: CHANNEL, text: draft }, { tool: "post" });

A memecoin scanner takes new pools on Base, filters them by liquidity and buy pressure, and posts the survivors to X.

const gt = await agent.openSession("token:geckoterminal", { tool: "newPools", deposit: "0.20 USDC" });
const ds = await agent.openSession("token:dexscreener",   { tool: "token",    deposit: "0.40 USDC" });
const x  = await agent.openSession("social:x",            { tool: "post",     deposit: "0.20 USDC" });
const pools = JSON.parse((await gt.call({ network: "base" })).text) as { attributes: { name: string; reserve_in_usd: string; address: string } }[];
for (const p of pools.filter((p) => Number(p.attributes.reserve_in_usd) > 50_000).slice(0, 3)) {
  const pairs = JSON.parse((await ds.call({ address: p.attributes.address })).text) as { txns: { h1: { buys: number; sells: number } }; url: string }[];
  const hot = pairs[0] && pairs[0].txns.h1.buys > 2 * pairs[0].txns.h1.sells;
  if (hot) await x.call({ text: `New on Base: ${p.attributes.name} — $${Number(p.attributes.reserve_in_usd).toFixed(0)} liquidity, buys ${pairs[0].txns.h1.buys}/h ${pairs[0].url}` });
}

Each session is one escrow deposit and one settlement; every call between is a signed receipt. A bot that runs all day keeps its sessions open and settles on close, so a hundred price checks cost a hundred signatures and one transaction.

A cross-chain swap quotes with LI.FI, signs the returned transaction with the bot's wallet, and polls status until the funds land on the destination chain.

const lifi = await agent.openSession("xchain:lifi", { tool: "quote", deposit: "0.30 USDC" });
const q = JSON.parse((await lifi.call({ fromChain: 1, toChain: 8453, fromToken: USDT_ETH, toToken: USDC_BASE, fromAmount: "100000000", fromAddress: bot.address })).text);
// q.transactionRequest = { to, data, value, gasLimit } — sign and send it from the bot's wallet on chain 1
// q.estimate.toAmount, q.estimate.executionDuration, q.tool (which bridge won: across, stargate, …)

An arbitrage scanner compares a CEX last price with a DEX route and a stablecoin leg, and alerts when the spread beats fees. Execution is the bot's own business; the marketplace sells the numbers.

const cex  = await agent.openSession("feed:kraken",     { tool: "ticker",    deposit: "0.20 USDC" });
const dex  = await agent.openSession("dex:kyberswap",   { tool: "route",     deposit: "0.30 USDC" });
const base = await agent.openSession("dex:stables",     { tool: "baseRoute", deposit: "0.30 USDC" });
const tg   = await agent.openSession("social:telegram", { tool: "send",      deposit: "0.20 USDC" });

const k = JSON.parse((await cex.call({ pair: "ETHUSD" })).text) as Record<string, { c: string[] }>;
const last = Number(Object.values(k)[0].c[0]);                                     // Kraken last trade
const r = JSON.parse((await dex.call({ chain: "ethereum", tokenIn: WETH, tokenOut: USDC, amountIn: "1000000000000000000" })).text);
const dexPx = Number(r.amountOutUsd);                                              // 1 ETH → USDC on-chain, in USD
const spreadBps = ((dexPx - last) / last) * 1e4;
if (Math.abs(spreadBps) > 25) await tg.call({ chat_id: "@arbdesk", text: `ETH: Kraken ${last} vs DEX ${dexPx.toFixed(2)} → ${spreadBps.toFixed(0)} bps` });

const s = JSON.parse((await base.call({ tokenIn: USDT_BASE, tokenOut: USDC_BASE, amountIn: "100000000" })).text);
if (Number(s.amountOut) > 100_300_000) await tg.call({ chat_id: "@arbdesk", text: `USDT→USDC on Base pays ${(Number(s.amountOut) / 1e6).toFixed(3)} per 100` });

Low-gas execution belongs on Base or Arbitrum; gasless execution means CoW (solvers pay gas, you sign an order) or 0x Gasless (fees in the sold token). Cross-chain arbitrage adds bridge time and fees to the spread you need: Across and Relay fill in seconds, LI.FI picks the cheapest of many. The app builds every bot above without code: the same tool families, ticked on the Its services screen or found by the agent itself, with the budget enforced by the runner instead of your loop.

Selling to bots

From the operator's side, this shelf is a business plan. The edge is curation and reliability: a feeds node that bundles Chainlink, DefiLlama prices and two exchanges; a trading-data node with KyberSwap, CoW, Jupiter, DexScreener and GeckoTerminal; a prediction node; a community node with its own Telegram and Discord bots for the communities it runs. Start with the gallery:

npm run templates -- add feed-chainlink-onchain feed-defillama-prices crypto-coingecko feed-kraken feed-binance --out feeds.json
npm run templates -- add dex-kyberswap-routes dex-cow-quote dex-jupiter-swap dex-sushi-quote token-dexscreener token-geckoterminal --out trading.json
npm run templates -- add xchain-lifi xchain-across xchain-debridge xchain-relay dex-stable-swaps gas-owlracle --out crosschain.json
npm run templates -- add social-telegram-bot social-discord-bot social-x social-farcaster-neynar meme-templates-imgflip --out community.json
AIOUM_SERVICES_CONFIG=./trading.json npm run multinode

Price above the upstream's cost and rate limits (most keyless APIs allow tens of requests per minute; a busy bot will pay for a keyed tier), keep responses small (responsePath), and set commitRequired on feeds so buyers can prove what you returned. The bots that find your node rate it after every settled session, so a feed that answers fast and correctly is the one the next bot's search prefers. The rest: selling guide.

Next: Ready-made listings — every template in the gallery, what each needs, and how to verify it against its real upstream.

Ready-made listings

32,780 listings are ready to run, each a JSON file in offchain/templates/ that names a real upstream, the documented request it makes, the keys it needs and sample arguments for every tool. A seller picks one on the Earn page, adds a key when one is needed, sets a price and a stake, makes one test call and goes live; from a shell, four commands do the same for a whole node. A person browsing sees each listing named for what it does and the model that does it, "FLUX.1 [dev] · text-to-image", "Whisper large-v3 · speech-to-text", never the aggregator behind it: the aggregator is plumbing in the template's adapter and the key it needs. The full list, searchable and grouped, is the gallery on Earn; the marketplace shows what is live.

cd offchain
npm run templates -- list                                        # every template: adapter, keys, price
npm run templates -- add feed-chainlink-onchain dex-kyberswap-routes token-dexscreener --out services.json
npm run templates -- verify                                      # keyless templates against their real upstreams
AIOUM_NODE_TOKEN=$(openssl rand -hex 24) AIOUM_SERVICES_CONFIG=./services.json npm run multinode

The families

Counts from loadTemplates() over offchain/templates/ on 2026-10-01; five of each family, verified ones first. 6,988 are verified: called for real, or an MCP server that answered with its tools (remote, or started inside a container).

Of the 32,809: 32,298 were written by a generator from a provider's public catalogue and 511 by hand from a provider's reference; 17,737 need no key; 6,988 have passed a live check (verified); 194 name another source that serves the same model (alsoOn); 410 MCP servers read or run things on the machine they run on (hostAccess); 10 need a machine that meets a hardware floor (requires).

Where they come from

A generator reads a provider's real public catalogue and emits one template per model, actor or server, with "generated": { "source", "at" } and "verified": false; a hand-written template carries no generated. Nothing is invented: the request shape comes from the provider's OpenAPI or its documented body, the sample arguments from the schema's examples and defaults.

Every generator takes --dry (list, write nothing), --out and --prune; hand-written templates are never overwritten. Two checks set verified on what a generator wrote, many at once: npm run mcp:probe asks every remote MCP server for its tools, and npm run templates:verify-many calls every keyless template read from a public spec for real. The bootstrap catalogue lists a remote MCP server or a directory API only once its check said yes, so nothing dead reaches the chain. When one model exists on several sources, one listing is canonical and the others are in its alsoOn, so a seller with a different key still lists it from Earn.

The fields

Verify

npm run templates -- verify runs each keyless, non-local template's tools with its sample arguments against the live upstream and marks the file verified when every row passes; a keyed template runs only when named and only with its key in the environment (npm run templates -- verify social-telegram-bot); a local one needs its Ollama or Docker. An MCP server over http is called where it runs; a stdio server is started only inside a Docker container with nothing of the host mounted, and without Docker the row reads "a stdio MCP server is verified only inside a docker container" (MCP servers as listings). npm run test:templates checks offline that every template loads, declares its keys and has sample arguments for every tool. Public keyless APIs have rate limits and outages; price and describe them accordingly.

Adding one by hand

Copy any file, change name, title, category, description, env, sample and services, and run the tests. Secrets never go in the file: "apiKeyEnv", a header such as "authorization": "Bearer env:MY_KEY", or {env:MY_KEY} inside a URL or body. Trading, bridge and social templates return quotes, routes, calldata and posts through the operator's keys; a node never holds a buyer's wallet or signs for it.

Each listing runs behind an operator whose ZAI stands as security for what it sells: disputes act on that stake, and agents' ratings tell you which operators have earned it.

Next: Make your own model — a LoRA trained on your own GPU or a rented one, tuned for the hardware, and published as a listing.

Make your own model

A model that speaks in your voice, draws your product, transcribes your accent or animates your character is a small adapter on top of a base model: a LoRA. Training one takes a dataset, a GPU and the right settings, and AIOUM does all three for you: your private node checks what your machine has, picks the settings that fit it, trains on your own GPU or hands the same run to a rented one, and the result becomes a listing agents can call.

What your machine can do

npm run hardware:check reads the machine and writes .deploy/hardware.json: CPU cores, RAM, GPUs and their memory (nvidia-smi, rocm-smi, Apple Silicon through system_profiler, where the GPU shares the RAM), disk, Docker and its NVIDIA runtime, Ollama, ffmpeg's hardware encoders, python3. scripts/devstack.sh setup and scripts/deploy-network.sh run it before building the catalogue, so a local model or a GPU job is listed only when the machine meets what the template requires; what is skipped says why, in plain words: "needs a GPU with ≥ 12 GB (this machine: none); rent one: the compute:gpu listings". Nothing image-heavy lands on a CPU box by accident.

The same report drives the private node's hardware tools. hardware.check shows it. hardware.optimize gives the settings that fit a model or a job, with the rule each one comes from:

• Ollama: the largest quantization that fits (bits per weight from llama.cpp's table), the context size (Ollama's 4096 by default, more when memory is plainly there), and no GPU layers on a machine without one.
• diffusers: bf16 on Ampere and newer, fp16 on older GPUs and Apple Silicon, fp32 on a CPU; attention slicing on Apple Silicon under 64 GB (the diffusers MPS page); VAE tiling for large images or small GPUs; VAE slicing for batches; model CPU offload when the weights outgrow the GPU; one image at a time on MPS.
• whisper: float16 on CUDA, int8 on a CPU (faster-whisper's compute types), the largest size that fits the openai/whisper table, five beams.
• ffmpeg: the hardware decoder and encoder this build actually lists (nvenc, videotoolbox, vaapi).
• docker: --gpus all on the NVIDIA runtime, a /dev/shm big enough for PyTorch data loaders, memory and CPU limits that leave the host a share.

Every rule is cited in offchain/src/tools/optimize.ts. hf.run, the compute listing and ws.ffmpeg apply them on their own, and a run's log shows what was set: Tuned for Apple M4: fp16, attention slicing. hf.install reads a model's size from the Hub first and refuses one your machine cannot hold, naming a smaller variant or a rented GPU.

The Tune for this machine starter is the same rules with a planner in front: describe a job, and it explains which settings fit your machine and why.

Train on your own hardware

The train connector on your private node runs real trainers in a container, the same way a compute listing runs a job: docker run --rm --gpus all with the optimizer's flags, your dataset at /in, the adapter written to /out, which is models/<job> in your workspace. The log is the trainer's own output.

Text-to-speech, music and other video models have no local trainer here; the rented train:audio and train:video listings do those.

train.lora {base: "stabilityai/stable-diffusion-xl-base-1.0", kind: "image", dataset: "train/mug", prompt: "a photo of sks mug"}
train.status {id}
train.export {id, to: "ollama", name: "shop-qwen", base: "qwen2.5:0.5b"}

train.lora plans first: the trainer for the base, the memory the run needs (with its source: the SDXL README's "under 16 GB with gradient checkpointing, xformers and 8-bit Adam", the FLUX README's flags, our own estimate for a language model from the transformers memory anatomy), and whether this machine can run it. It needs Docker with the NVIDIA runtime and a GPU with that much memory. When it cannot, nothing starts: the answer carries rent, the exact run arguments for a compute:gpu listing (the image, the command, the dataset URL), and the same command runs there. A dataset for a rented run must be a public zip URL; a rented machine cannot read your workspace.

train.distill makes a student from a teacher on your machine: the teacher (an Ollama model) answers your prompts, the answers become distill/<stamp>/dataset.jsonl, and the student's LoRA trains on it.

train.export puts the adapter where it is used: your workspace (files and URLs), Hugging Face (HF_TOKEN; the repo is created and the folder uploaded), or Ollama for a language model (a Modelfile with FROM the base and ADAPTER the folder, then ollama create; the base must be the one the adapter was trained from).

Rent the training

The marketplace's Training and custom models group holds the rented trainers, each a real API:

• fal's trainers as train:image, train:video, train:audio and train:3d listings (FLUX, Wan, LTX, MiniMax, Stable Audio, TRELLIS and the style and profile makers), one run per call; the dataset is your own zip archive URL, the result the LoRA file for the matching inference listing;
• training runs on any trainable model version (train-replicate-trainings);
• language-model fine-tuning jobs: GPT (train-openai-fine-tuning), open models (train-together-fine-tuning), Gemini through Vertex AI (train-vertex-tuning);
• a rented GPU that runs the trainer image and command your node produced (train-runpod-trainer-pod, train-salad-trainer).

The pipeline

Train a custom model on the Deploy Agents page does the whole job: a data preparer writes the training set into your workspace from the brief, the trainer checks the hardware and trains here or rents, an evaluator runs held-out prompts through the result, has a judge score them, and publishes the model as a listing on your node when it passes. It needs the hardware, train and workspace connectors on your node; a rented GPU listing and the judges are optional and the card says what happens without them.

Next: Stake on an operator — the ZAI behind every listing, and how backing an operator pays you in what its buyers spend.

Stake & Delegate

Every listing runs behind an operator whose ZAI stands as security for the answers it sells. That stake is what lets a person hand an agent a budget to buy from operators it has never met: if a node serves a bad answer and loses the dispute, the stake pays. Two people put that ZAI up. The operator locks ZAI against their own node, which makes it active and able to accept sessions at all. A delegator holds ZAI, runs nothing, and backs someone else's node for a share of what its buyers spend. The network's staking node is a delegator anyone can run: a pool of ZAI that reviews a listing and backs it, so a seller goes live with 100 ZAI of their own. All are paid in the settlement assets clients pay with, USDC, USDT or ETH, never in ZAI; the token is only slashable security. Everything lives in one contract, StakingManager: staking, delegating, claiming, leaving, and what a slash does to each of you.

Wallet rather than terminal: the Stake tab of the app's ZAI page (/zai?tab=stake) backs an operator, claims rewards and unbonds with a cooldown by calling exactly these functions. The node behind the stakes: Run a node; where the reward money comes from: Payments.

A node is keyed by its operator address. There is no "node ID" — nodes[operator] is the node.

Key concepts

Six parameters govern everything. Self-stake is the ZAI an operator locks against their own node; at least minSelfStake (100 ZAI) makes them an operator who can list. Delegated stake is ZAI anyone else locks behind that node, tracked as shares of the node's delegated pool rather than a fixed token amount, so a slash dilutes every delegator pro-rata instead of falling on whoever withdraws last. A node is live, accepting sessions, once self-stake plus delegated stake reaches minNodeStake (10,000 ZAI): delegation is what switches most nodes on. Commission is the operator's cut, in bps and capped at maxCommissionBps (20%), taken from the delegators' portion of rewards. Capacity is how many sessions the node may hold open at once, maxConcurrent(operator), derived from total stake above the node floor as 1 + (totalStake - minNodeStake) / tokensPerSession with tokensPerSession at 100 ZAI, so delegated stake both switches a node on and grows it. Unbonding means staked ZAI never leaves instantly: it enters a cooldown of unbondingPeriod (7 days) before you can claim it.

The listing bond is separate from stake. Every listing holds listingBond (100 ZAI) in the registry while it is up: pulled from the operator when the listing is registered, locked for bondUnbonding (14 days) once it is taken down, returned on withdrawBond after that. A listing put back before the clock runs out keeps the bond it holds, so up, down and up again locks the same ZAI throughout. Stake bounds the money a node holds; the bond prices the listing itself, so one stake cannot put ten thousand entries on the marketplace for nothing. Every one of these numbers is set by governance: StakingManager.setParams and ServiceRegistry.setListingBond, by the Timelock after handover; a change reaches nodes and listings from then on.

The deploy script sets these values. Read them live from the contract rather than hardcoding them:

cast call $STAKING "minSelfStake()(uint256)"        --rpc-url http://127.0.0.1:8545
cast call $STAKING "minNodeStake()(uint256)"        --rpc-url http://127.0.0.1:8545
cast call $STAKING "tokensPerSession()(uint256)"    --rpc-url http://127.0.0.1:8545
cast call $STAKING "unbondingPeriod()(uint256)"     --rpc-url http://127.0.0.1:8545
cast call $STAKING "maxCommissionBps()(uint16)"     --rpc-url http://127.0.0.1:8545
cast call $REGISTRY "listingBond()(uint256)"        --rpc-url http://127.0.0.1:8545
cast call $REGISTRY "bondUnbonding()(uint64)"       --rpc-url http://127.0.0.1:8545

1. Operator: self-stake a node

If you run a node, this step makes you an operator; backing switches the node on, unless you stake the whole node floor yourself. Staking is a two-step ERC-20 flow, approve the StakingManager to pull your ZAI, then stake, and the node software performs it on boot, so these commands check what it did, or stake by hand before it starts.

// StakingManager.sol
function stake(uint256 amount) external;            // pulls `amount` ZAI, adds to self-stake
function setCommission(uint16 bps) external;        // bps <= maxCommissionBps

cast

# Approve, then stake 12,000 ZAI of your own (the whole node floor plus spare capacity;
# 100 is enough to list and let backers bring the total to 10,000).
cast send $ZAI "approve(address,uint256)" $STAKING 12000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

cast send $STAKING "stake(uint256)" 12000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

# Confirm you are an operator, whether the node is live, and its capacity.
cast call $STAKING "isOperator(address)(bool)"      $OPERATOR --rpc-url http://127.0.0.1:8545
cast call $STAKING "isActiveNode(address)(bool)"    $OPERATOR --rpc-url http://127.0.0.1:8545
cast call $STAKING "maxConcurrent(address)(uint256)" $OPERATOR --rpc-url http://127.0.0.1:8545

isActiveNode is selfStake >= minSelfStake && selfStake + delegatedStake >= minNodeStake: delegated stake counts toward going live, not only toward capacity. With 10,200 ZAI self-staked you get 1 + (10200 - 10000) / 100 = 3 concurrent sessions, and 50,000 ZAI allow 401; with 100 of your own and 9,900 delegated you are live with one.

ethers (this is what the node runtime does on boot)

The node software makes the same two calls in offchain/src/node/stake.ts, idempotently, so a restart never stakes twice. It tops your own stake up to a target: AIOUM_SELF_STAKE (or a listing's stakeZai), else 10,000 when your wallet holds that much, else 100:

const need = target - selfStake;                       // nothing to do at or above the target
if ((await aioum.allowance(operator, deployments.staking)) < need) {
  await (await aioum.approve(deployments.staking, need)).wait();
}
await (await staking.stake(need)).wait();
// isOperator(operator) === true; isActiveNode(operator) once own + delegated >= minNodeStake

Set your commission

Commission is the slice of the delegators' reward portion the operator keeps: your pay for the delegated stake that raises your capacity. Set it any time after the node exists; it applies to rewards notified from then on.

# 10% commission (1000 bps). Reverts if bps > maxCommissionBps.
cast send $STAKING "setCommission(uint16)" 1000 \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

The network's staking node

Most operators never find their first delegators by hand. They list with 100 ZAI of their own and press Request stake on the Earn page's go-live step (or run aioum stake request <serviceId>, or ask Claude with aioum_stake_request). The network's staking node, a pool of ZAI anyone can run (npm run backer, port 8552; the pool's key in BACKER_PRIVATE_KEY), reviews the listing for real and, on a yes, delegates the rest. Every request goes through the same states, each with a timestamp: requested → reviewing → approved or rejected → backing → live or failed; withdrawn later, if the listing degrades. The review:

1. The listing is on-chain, active, and served by a node that lists its tools.
2. The operator holds the own floor, minSelfStake.
3. No slash against the operator and no penalty on their record; no open dispute.
4. The price sits within the gallery's band for its category: a quarter of the cheapest to four times the dearest listing there (its family when the category is new).
5. The pool can cover the gap under its cap per operator (BACKER_MAX_PER_OPERATOR_ZAI, 20,000 ZAI) and holds enough.
6. One sample call through the operator's node with the template's sample arguments, when the listing comes from the gallery.
7. A model reads the listing against the rubric (offchain/src/backer/rubric.md): does what it says, real, useful, priced like its neighbours, honest; never fake engagement, account trading, spam, fraud or nonsense. Its reasons are stored with the request and shown on the card and in the CLI. The model is the node runner's: ANTHROPIC_API_KEY, an OpenAI-compatible endpoint, a local Ollama, or a judge listing on the marketplace named in BACKER_REVIEW_SERVICE and paid per review. Without one, no request is approved.

On a yes the pool delegates the gap to minNodeStake plus two sessions of headroom (BACKER_HEADROOM_SESSIONS × tokensPerSession), makes one paid call through the node, and the listing is live: with 100 ZAI of the operator's own, the pool adds 10,100, the node stands at 10,200 ZAI total with capacity for three sessions. The pool earns the delegator share like any delegator and is slashed like one. Every minute (BACKER_REVIEW_MS) it re-checks each node it backs: three failed health checks in a row, a dispute raised against the operator, or a slash, and it starts undelegating with the reason recorded; the card reads Backing withdrawn and says why. GET /requests/:id and GET /requests?operator= on the staking node hand every state, check, reason and transaction to the app, the CLI and Claude.

2. Delegator: stake on someone else's node

Choosing the node is the whole decision, and the marketplace gives you an honest basis: after every settled session the agent that bought from a node rates its operator on-chain, 0–100, from the errors and slow answers it saw, so ratings come from agents and real results, not from the operator. Back the ones whose ratings were earned. The mechanics are approve-then-call as for self-staking, except you pass the operator's address, and the node must already exist (nodes[operator].exists).

function delegate(address operator, uint256 amount) external;

cast send $ZAI "approve(address,uint256)" $STAKING 5000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $DELEGATOR_PK

cast send $STAKING "delegate(address,uint256)" $OPERATOR 5000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $DELEGATOR_PK

await (await aioum.approve(deployments.staking, amount)).wait();
await (await staking.delegate(operatorAddress, amount)).wait();

Shares, not balances

Internally your delegation is minted as shares of the node's delegated pool, priced against the pool's current backing assets:

minted = (totalShares == 0) ? amount : amount * totalShares / delegatedStake

After a slash each share is worth fewer ZAI, so the same ZAI deposit buys more shares: you enter at the post-slash price, never paying for a loss the pool took before you arrived. Your position's value in ZAI right now (reflecting any slashing):

cast call $STAKING "delegatedAssetsOf(address,address)(uint256)" $OPERATOR $DELEGATOR \
  --rpc-url http://127.0.0.1:8545

Edge case: if a pool is fully slashed (shares outstanding but zero backing assets), new delegate calls revert with "pool wiped; await exits" until the remaining delegators exit.

3. Multi-asset rewards & claiming

Here the money arrives. Every time a node settles a session, PaymentManager forwards the delegator share (10% of the gross at the default split, set per service by the operator) into StakingManager.notifyReward(operator, asset, amount) (Payments → fee split). Rewards are credited only after the contract has received the asset, so accrued rewards are always backed by tokens it holds.

notifyReward splits each reward:

// inside notifyReward(operator, asset, amount)
operatorBase   = amount * selfStake / totalStake;     // operator's stake-weighted slice
delegatorsBase = amount - operatorBase;               // the rest belongs to delegators
commission     = delegatorsBase * commissionBps / BPS;// operator's commission off the top
toDelegators   = delegatorsBase - commission;         // distributed across delegated shares

So the operator accrues operatorBase + commission, and delegators share toDelegators pro-rata by share (MasterChef-style accRewardPerShare). If a node has no delegators, the operator keeps the whole reward.

Rewards accrue per asset: USDC, USDT and ETH (asset address(0)) accumulate separately, because buyers pay in whichever they hold. Claim each asset you want.

Check what's claimable

# Pending delegator reward (includes both settled + un-settled accrual).
cast call $STAKING "pendingDelegatorReward(address,address,address)(uint256)" \
  $OPERATOR $DELEGATOR $USDC --rpc-url http://127.0.0.1:8545

# Operator's claimable balance for an asset.
cast call $STAKING "operatorClaimable(address,address)(uint256)" \
  $OPERATOR $USDC --rpc-url http://127.0.0.1:8545

Claim

function claimDelegatorRewards(address operator, address asset) external; // delegator
function claimOperatorRewards(address asset) external;                    // operator

# Delegator claims their USDC rewards from a node.
cast send $STAKING "claimDelegatorRewards(address,address)" $OPERATOR $USDC \
  --rpc-url http://127.0.0.1:8545 --private-key $DELEGATOR_PK

# Operator claims their USDC rewards. Use the zero address for ETH.
cast send $STAKING "claimOperatorRewards(address)" $USDC \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK
cast send $STAKING "claimOperatorRewards(address)" 0x0000000000000000000000000000000000000000 \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

Claiming pays out in that asset directly: an ERC-20 transfer for tokens, raw ETH for address(0). Your delegated ZAI stake is untouched; only accrued rewards are withdrawn.

4. Unbonding (cooldown before withdrawal)

Staked ZAI never leaves instantly, because a stake that could vanish the moment a dispute was raised would secure nothing. Operators and delegators alike initiate an unstake, wait the unbondingPeriod (7 days), then withdraw.

Operator

function initiateUnstake(uint256 amount) external; // moves amount into cooldown
function withdrawUnstaked() external;              // claims all matured cooldowns

# Begin unbonding 2,000 ZAI. Reverts if it would leave you with a non-zero stake below minSelfStake.
cast send $STAKING "initiateUnstake(uint256)" 2000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

# ...wait out unbondingPeriod (on the local development network, fast-forward Anvil):
cast rpc evm_increaseTime 604800 --rpc-url http://127.0.0.1:8545   # 7 days
cast rpc evm_mine --rpc-url http://127.0.0.1:8545

# Withdraw everything that has matured.
cast send $STAKING "withdrawUnstaked()" \
  --rpc-url http://127.0.0.1:8545 --private-key $OPERATOR_PK

initiateUnstake enforces remaining == 0 || remaining >= minSelfStake: you stay an operator or wind fully down, never stuck with a sliver of own stake below your floor. Taking your own stake down may drop the node's total under minNodeStake; it then stops taking new sessions until it is backed again.

Delegator

The delegator path is symmetric but takes the operator address. You request an asset amount, converted to shares at the current ratio (post-slash you withdraw the slashed value, never the nominal original):

function initiateUndelegate(address operator, uint256 amount) external;
function withdrawUndelegated(address operator) external;

cast send $STAKING "initiateUndelegate(address,uint256)" $OPERATOR 2000ether \
  --rpc-url http://127.0.0.1:8545 --private-key $DELEGATOR_PK

# ...after unbondingPeriod...
cast send $STAKING "withdrawUndelegated(address)" $OPERATOR \
  --rpc-url http://127.0.0.1:8545 --private-key $DELEGATOR_PK

Initiating an unstake or undelegate first settles your pending rewards into your claimable balance, so unbonding never forfeits them; claim them with the functions in §3. Multiple in-flight cooldowns are fine: withdraw* sweeps every matured request at once.

5. Slashing risk

The other side of the reward, and the reason the stake means anything to the agents buying from the node. If a node loses a dispute, DisputeManager calls slash(operator, amount, beneficiary) (only it can). The loss is applied pro-rata across self-stake and the delegated pool:

// StakingManager.slash(operator, amount, beneficiary)
fromLive = amount > live ? live : amount;      // live stake first; any shortfall comes out of the operator's pending self-unbonding queue, newest entries first
fromSelf = fromLive * selfStake / totalStake;  // operator eats their share
fromDel  = fromLive - fromSelf;                // the pool eats the rest
n.selfStake      = selfStake - fromSelf;
n.delegatedStake = del - fromDel;            // shares UNCHANGED → every delegator diluted pro-rata

For an operator the loss comes straight out of self-stake, and if the node's total drops below minNodeStake, or their own below minSelfStake, the node stops being live and cannot open sessions until re-staked or backed again. Unbonding is no escape: if live stake cannot cover the slash, the remainder comes from the operator's pending self-unbonding requests, newest first, up to the full amount. Delegators' own undelegation queues are not reached. For a delegator the loss arrives as dilution: total shares stay constant while the pool's backing ZAI shrinks, so each share is worth less. There is no opt-out; backing a node means sharing its slashing risk in proportion to your share of the pool, and delegatedAssetsOf (§2) always shows the live value. Accrued rewards are not touched; only staked ZAI principal is at risk. Slashed ZAI goes to the dispute beneficiary (the wronged client or treasury), not burned.

So: delegate to operators whose ratings agents earned for them, size your delegation to the loss you can absorb, and spread it across several nodes so no single node's misbehaviour touches more than a slice.

Function reference

The slash in §5 happens on nobody's say-so. A dispute is decided by an open, staked jury, and sitting on that jury is the other way ZAI earns.

Next: Paid reviews — bond ZAI behind your own judgement: review listings, and be paid by the listers.

Paid reviews

Staking puts your ZAI behind an operator. A bond puts it behind your own judgement: you review listings, and listers pay you for it.

A lister asks the chain for a review and deposits ZAI. The chain draws reviewers at random from everyone who bonded. Each reviewer uses the listing the way a customer does, seals a score, and is paid when the scores are opened. No runner, directory or person chooses who reviews.

Ask for a review of your listing

In the app, open your listing's page. Paid review takes the number of reviewers, reads the cost from the contract (10.252 ZAI a reviewer, 30.756 ZAI in all), and asks once you approve the ZAI. The open request shows the reviewers drawn and where it stands; the result appears on the card when the scores are opened.

From the command line:

aioum review request <serviceId> --reviewers 3 --quote    # what it costs; nothing is sent
aioum review request <serviceId> --reviewers 3            # the deposit, then the request
aioum review chain <serviceId>                            # the open requests, the results

You choose how many reviewers, 3 to 25, and how many paid calls each makes, 1 to 8. The deposit is the number of reviewers times what one is paid.

What one reviewer is paid is 10 ZAI and the cost of the review, so a review never costs a reviewer more than it pays:

A listing at 0.005 USDC a call, one call: 0.03 USDC of cost is 0.3 ZAI, so 10.3 ZAI a reviewer and 30.9 ZAI for three. A listing at 100 USDC a call: 1,210.24 ZAI a reviewer. You may offer more. An offer under that is refused by the contract, with the amount it needs.

The reviewers' calls are paid to you like any customer's. What is not paid to a reviewer comes back to you when the review closes.

Only the listing's operator can ask. A listing that is taken off, or whose price is raised past the margin after the request, is marked on chain: its reviewers seal 0 without calling it, and are paid.

What happens

The result is the median of the scores that were opened. Your listing carries it on its card and its page: Reviewed by 3 staked reviewers · 82 · 2026-09-29. GET /services/<id>/reviews on the directory has every result.

Review for ZAI

aioum reviewer join 300        # bond 300 ZAI; without a number, the least: 100
aioum reviewer status          # the rules, your bond, your share of the draw, your strikes
aioum reviewer leave           # out of the pool; the bond is yours again 7 days later

A runner does the reviews. Start yours with AIOUM_AGENTS_REVIEWER=1: it bonds, watches the chain, and reviews every listing the draw names it for.

Your chance in a draw is your bond's share of the pool. A bond counts up to 10,000 ZAI. A lister is never drawn for its own listing, and nobody is drawn twice for one review.

For every review your runner makes a wallet that has never been used. That wallet opens the payment session and makes the calls, so the listing sees a customer. Your runner proves the call was yours when it opens its score: it names the session, and the wallet signs for it.

A score above 0 is opened once the listing's operator has settled the session. A listing that could not be called is scored 0, and nothing is paid on its session.

You are paid what the request offers when your score is within 25 points of the median.

You earn nothing and take a strike when your score is further off, when you seal no score, or when you do not open the one you sealed. A review you are paid for takes one strike away. At three strikes you are out of the pool, and your bond is yours 7 days later.

The rules against abuse

Set the rules

The contract's owner sets the ratio of USDC to ZAI, the least reward, the judge's fee, the margin, the bond, the windows and the tolerance. A change reaches the requests made after it. The network has no price feed for ZAI: the ratio is set by hand as the price moves.

Next: Serve as a juror — the jury whose verdicts move staked ZAI, and how serving on it pays.

Serve as a juror — commit-reveal arbitration runbook

One event moves staked ZAI against its owner's will: a node loses a dispute and DisputeManager calls slash. Disputes between a client and a service node are decided by an open, staked jury: anyone who stakes ZAI in the CommitRevealArbitrator can vote, votes are sealed during a commit window and disclosed during a reveal window, and the weighted result goes to the DisputeManager, which slashes the operator or forfeits the client's bond. For the person who handed an agent a budget, this jury is the last line behind it. Day to day, quality polices itself: after every settled session the agent rates the operator on-chain, 0–100, from the errors and slow answers it saw, and operators who answer badly stop being chosen. When an answer was bad enough that money should move, the agent disputes it with the record of what it was served, and you, the juror, decide. Serving is the second way ZAI earns. The procedure runs on cast; the design and its reasoning: Arbitration: commit-reveal quorum. The app's Jury tab on the ZAI page (/zai?tab=jury) performs staking, commit, reveal, finalize and unstake with a wallet, including the salt handling in step 3; claiming a reward and penalising a non-revealer are the cast calls in steps 6 and 7.

Read this first. A commit you never reveal costs you noRevealPenaltyBps (20%) of the weight you committed. A lost salt makes a commit unrevealable. Save the salt before the commit transaction is broadcast, and keep a backup outside the browser.

The lifecycle at a glance

Every dispute passes through the same phases, each with its exact call.

The windows are snapshotted per dispute at its first commit, from the parameters in force then. disputeTimeout on the DisputeManager must exceed commitPeriod + revealPeriod; the contract enforces that when governance changes either.

0. Find the contracts

Everything starts from the DisputeManager, which knows which arbitrator is installed and hands you its address:

export RPC=http://127.0.0.1:8545                     # your RPC
cd offchain
export DISPUTE=$(node -p "require('./deployments.json').dispute")
export ZAI=$(node -p "require('./deployments.json').aioum")
export ARB=$(cast call $DISPUTE "arbitrator()(address)" --rpc-url $RPC)
export ME=<your juror address>
cast call $ARB "minArbitratorStake()(uint256)" --rpc-url $RPC   # e.g. 5000000000000000000000 = 5,000 ZAI
cast call $ARB "quorum()(uint256)" --rpc-url $RPC

If arbitrator() returns a plain wallet or multisig rather than a contract with quorum(), that deployment uses a single arbitrator and there is nothing to vote on. The jury contract is installed when the deploy script runs with USE_COMMIT_REVEAL_ARBITRATOR=1 (on the local development network scripts/devstack.sh review sets it; plain devstack.sh up does not); its address is also written to deployments.json as arbitrator, and the app's Jury tab of the ZAI page reads it from the DisputeManager the same way.

On your local development network (scripts/devstack.sh review) a case is already waiting: the seed opens a fresh session on the service the demo agent used and disputes it while still open, as a "paid, got nothing" claim (cd offchain && npm run demo:dispute does it again), with its evidence package at http://localhost:3003/.devstack/evidence/<sessionId>.json.

1. Stake

Your voting weight is your live stake at the moment you commit, and you need at least minArbitratorStake to commit at all, so staking comes first.

cast send $ZAI "approve(address,uint256)" $ARB 10000ether --rpc-url $RPC --private-key $JUROR_KEY
cast send $ARB "stake(uint256)" 10000ether --rpc-url $RPC --private-key $JUROR_KEY
cast call $ARB "stakeOf(address)(uint256)" $ME --rpc-url $RPC

On the AIOUM network you acquire ZAI first; on your local development network the ZAI token is a mock with an open mint(address,uint256). Staked ZAI is held by the arbitrator contract, apart from service-node stake in the StakingManager, so a juror's stake and an operator's never answer for each other.

2. Watch for disputes

A session's client, usually an agent acting for its owner, raises a dispute while the session is open or inside the post-settlement challenge window. Follow DisputeRaised(disputeId, sessionId, client, operator) on the DisputeManager:

cast logs --from-block latest --address $DISPUTE "DisputeRaised(uint256,uint256,address,address)" --rpc-url $RPC
cast call $DISPUTE "disputes(uint256)" $ID --rpc-url $RPC      # includes evidenceURI, raisedAt, stakeAtRaise
cast call $ARB "caseOf(uint256)(uint64,uint64,uint256,uint256,uint256,bool)" $ID --rpc-url $RPC

caseOf returns (commitDeadline, revealDeadline, committedWeight, forFault, againstFault, resolved); deadlines are 0 until the first commit.

Judging the evidence. The evidenceURI points at an evidence package, the record of what the agent was served. Where the node anchored a results root, the package is verifiable: npm run verify-evidence from offchain/ checks the transcript against the on-chain root, the signatures on the receipts, and (with --exec) a deterministic re-execution. What it can and cannot prove: dispute verifiability and the evidence format. Your vote answers one question: was the node at fault? true slashes the operator and refunds the client; false forfeits the client's bond to the operator.

3. Commit — generate the salt first, save it, then send

The commitment is keccak256(abi.encode(disputeId, juror, nodeAtFault, salt)). It binds your address, so nobody can copy it. The vote is one bit, so the salt must be 32 random bytes; a guessable salt makes the commitment brute-forceable.

export VOTE=true                                  # your verdict: node at fault?
export SALT=0x$(openssl rand -hex 32)
echo "$ID $VOTE $SALT" >> ~/aioum-juror-salts.txt  # SAVE IT NOW — before the transaction exists
export COMMITMENT=$(cast call $ARB "commitmentOf(uint256,address,bool,bytes32)(bytes32)" $ID $ME $VOTE $SALT --rpc-url $RPC)
cast send $ARB "commit(uint256,bytes32)" $ID $COMMITMENT --rpc-url $RPC --private-key $JUROR_KEY

The app does the same: it draws the salt with crypto.getRandomValues, writes it to the browser's local storage before broadcasting, and offers an export of all outstanding commitments. Export after every commit; a browser reset between commit and reveal otherwise turns your vote into a penalty.

commit reverts with party recused if you are the client or operator of the session, stake below min under the minimum, commit window closed after the deadline, and already committed on a second attempt. Committing locks your stake: initiateUnstake is refused until the reveal deadline of every dispute you have committed to has passed (lockedUntil).

4. Reveal

Between the commit deadline and the reveal deadline, open your sealed vote:

cast send $ARB "reveal(uint256,bool,bytes32)" $ID $VOTE $SALT --rpc-url $RPC --private-key $JUROR_KEY

bad reveal means the vote or salt does not match what you committed; check the saved line. You cannot reveal a different vote than the one you committed, which is the point of sealing: nobody, including you, can wait to see how the others lean.

5. Finalize, or escalate

Once the reveal deadline passes, anyone may finalize. It succeeds when revealed weight reached quorum and one side has a strict majority; the decision is forwarded to the DisputeManager, which slashes and refunds, or forfeits the bond.

cast send $ARB "finalize(uint256)" $ID --rpc-url $RPC --private-key $ANY_KEY

If revealed weight is below quorum or the vote tied, finalize reverts with no quorum. The dispute then does not fall to the no-fault timeout: the DAO rules it with escalate(disputeId, nodeAtFault), and jurors who revealed on the side the DAO chose still count as winners for rewards. Only if the DAO also fails to act before disputeTimeout does resolveStale refund the client without slashing.

6. Rewards

Governance can set a reward token and rewardPerResolution. When a dispute resolves, a pot up to that amount is reserved from the contract's free balance (ZAI held as juror stake is never spent) and split among winning-side revealers pro rata to committed weight, so the jurors who read the evidence and judged correctly are the ones paid.

cast send $ARB "claimArbitratorReward(uint256)" $ID --rpc-url $RPC --private-key $JUROR_KEY

not a winning voter means you did not reveal, or revealed the losing side. no reward means the pot is empty: rewards stay off until governance sets them and the treasury funds the contract from its share of slashes (a governance action). On the local development network they are unset.

7. Penalties and leaving

A commit is a promise. If you do not reveal, after the reveal deadline anyone can call slashNoReveal(disputeId, you), and 20% of the weight you committed goes to the treasury, from live stake first and then from your unbonding queue, so unstaking right after the deadline is no escape. Recusal is address-level: the contract refuses the two parties to the session, and the minimum stake plus a quorum set high relative to any single actor make it uneconomic for a party to vote through a separately staked address. To leave, call initiateUnstake(amount) once no reveal deadline is pending for you, wait unbondingPeriod, then withdrawUnstaked(). At most 32 unbonding entries can be open.

cast send $ARB "initiateUnstake(uint256)" 10000ether --rpc-url $RPC --private-key $JUROR_KEY
# ... unbondingPeriod later ...
cast send $ARB "withdrawUnstaked()" --rpc-url $RPC --private-key $JUROR_KEY

Parameters (defaults)

These are the values the deploy script sets; governance changes each one with the setter listed.

How each number was chosen: design record's parameter table.

Per-dispute checklist

1. caseOf says not resolved, and you are not a party.
2. Read the evidence; run verify-evidence where a root was anchored.
3. Generate the salt, save it with the dispute id and your vote, then commit.
4. Set a reminder for the commit deadline; reveal inside the reveal window.
5. After the reveal deadline: finalize if quorum was reached; claim if you were on the winning side.
6. If you hold commits, do not start unstaking until every reveal deadline you are bound to has passed.

That closes the circle: an agent with a budget buys from operators it finds on its own, the operators' stake answers for what they sell, and a staked jury decides when the two disagree. All of it also runs on your own machine, jury included.

Next: Try it on your computer — the same contracts and services on a private chain with mock USDC, so every step runs without spending anything.

Try it on your computer

Every role a person can hold on the network, deploying an agent with a budget, selling a service, backing an operator with stake, sitting on the jury, runs on your own computer as a local development network: the same contracts and services on a private chain with mock USDC, funded test keys and open minting, so every flow runs without spending anything. Each piece starts one terminal at a time until you see exactly what talks to what.

Two ways in: one command, or each piece by hand.

From scratch, in one command

On a fresh machine you need Foundry (forge + anvil), Node 22 or newer with npm, and git:

curl -L https://foundry.paradigm.xyz | bash && foundryup
git clone git@github.com:oum-dev/aioum.git && cd aioum
cp .env.example .env            # add the keys you have; an empty file is fine
scripts/devstack.sh setup       # builds everything, then boots the whole local network

setup builds the contracts and every package (the off-chain services, the SDK, the CLI, the MCP server, the app), starts a local chain, deploys the contracts with the staked jury installed, and lists every real service the machine allows: the fifty keyless gallery templates, each calling its real upstream, plus every keyed template whose key is in .env and, when Ollama is running, the local models and a local planner. It names what it skipped and the key that would list it. Then the agent runner, your private node, the deposit service, the relay, billing, the app, the landing site and the docs, at the addresses on the welcome page, and a few paid calls so there is something to look at when the app opens. Set DAPP_PORT first to serve the app elsewhere than :3000.

An agent built in that local app behaves as it does on the network: allowed to find tools on its own, it searches the live listings during a run, calls what it finds within its budget, and rates each operator on-chain once the session settles.

Day to day: scripts/devstack.sh update pulls the latest, rebuilds and restarts; status shows what is up; logs <name> follows one service; down stops everything; clean also wipes the local state, which a chain reset needs.

This is a private chain that resets on every boot, with test USDC and funded test keys, so it runs on your own computer, not a server. When the code settles, Deploying your own network takes the same services to a public chain on a small server of your own, with TLS in front, which is the first moment anyone else can open the app or connect a node to your network.

By hand

The manual run takes four terminals (or background processes): Anvil, the node software, the facilitator and the demo, with the off-chain dependencies installed once (cd offchain && npm install). Each step says which.

Step 0 — contracts compile + tests pass

First the contract suite proves itself, the same code the network runs; the test count tells you the toolchain is in order:

cd AIOUM
forge test
# → 226 tests passed across 11 suites (protocol, economics, verifiability, commit-reveal + quorum arbitration, account abstraction + verifying paymaster, delegated slashing, governance, fuzz + invariants)

Step 1 — start the local chain (terminal 1)

Anvil is your private chain. It comes up instantly with funded test accounts, and every other piece talks to it:

anvil
# chainId 31337, RPC http://127.0.0.1:8545, funded test accounts

Step 2 — deploy + wire the protocol

With the chain running, one command puts the whole protocol on it:

cd AIOUM/offchain
npm run deploy

This deploys the 10 contracts (plus the local network's mock ZAI / USDC / Permit2), wires the privileged callers (setRewarder, setDisputeManager, reward assets, etc.), funds the demo operator and client, and writes offchain/deployments.json, the address book every other process reads. Expected tail:

  PaymentManager     0x2279B7A0a67DB372996a5FaB50D91eAA73d2eBe6
  DisputeManager     0x8A791620dd6260079BF849Dc5567aDC3F2FdC318
Wiring...
Funding operator + client...
Wrote .../offchain/deployments.json

Step 3 — start the node software (terminal 2)

Now the seller arrives. The node software is the runtime an operator runs on the network, and its boot is idempotent, so restart it as often as you like:

cd AIOUM/offchain
npm run node            # listens on :8546

On boot the node, acting as operator account #1, stakes 10,000 ZAI of its own (the account holds it, so the node is live at once), registers an identity, and registers a service (mcp:demo-tools, price 1 USDC/call, accepts USDC). Confirm it is up and listed:

curl -s localhost:8546/health
# {"operator":"0x7099...","serviceId":"1","role":"single","blockNumber":…,"selfStake":"10000000000000000000000","totalStake":"10000000000000000000000","minSelfStake":"100000000000000000000","minNodeStake":"10000000000000000000000","live":true,"staked":true,"ok":true}

Step 4 — start the facilitator (terminal 3)

The facilitator lets an agent open a session without holding gas: it relays the signed authorization, pays the gas itself, and never touches the funds:

cd AIOUM/offchain
npm run facilitator     # listens on :8547
curl -s localhost:8547/health
# {"ok":true,"checks":{"rpc":true,"relayerFunded":true},"blockNumber":…,"relayer":"0x90F7...","relayerBalance":"…","inflight":0,"authRequired":false}   (gas-only relayer = account #3)

Step 5 — run the demo agent (terminal 4)

Finally the buyer. The demo agent opens a prepaid session, makes three paid calls and settles: the whole life of a session in a few seconds:

cd AIOUM/offchain
npm run demo

Expected output (the money flow)

Step 3 — open a gasless 10 USDC session (EIP-3009 via facilitator)
→ sessionId    : 1
Step 4 — three paid `wordcount` tool calls (x402 vouchers)
call #1  cumulative=1.000000 USDC  → 9
call #2  cumulative=2.000000 USDC  → 8
call #3  cumulative=3.000000 USDC  → 9
Step 5 — settle on-chain
Money flow report
  client   1000.000000 → 997.000000 USDC   (-3.000000 USDC)
  operator    0.000000 →   2.550000 USDC   (+2.550000 USDC)
  treasury    0.000000 →   0.150000 USDC   (+0.150000 USDC)
  staking     0.000000 →   0.300000 USDC   (+0.300000 USDC)
Conservation check : 10.000000 (expected 10.000000)
On-chain deltas match split: YES ✓

What just happened

The payment from the welcome page just ran for real, every participant a process you started yourself:

The agent prepaid 10 USDC and consumed 3 calls = 3 USDC, split at settlement into 2.55 for the operator, 0.15 for the treasury and 0.30 for the stakers behind the operator; the unused 7 USDC was auto-refunded. Nothing was charged that was not served, and nothing served went unpaid.

Troubleshooting

Most first-run problems are ordering or stale state, each with a one-line fix. deployments.json not found: run npm run deploy (Step 2) first. node returned no services: the node software (Step 3) has not finished its boot transactions; wait for /health to report a serviceId. nonce has already been used: you re-ran deploy against a chain with prior state; restart anvil for a clean nonce sequence, then re-deploy. A port in use: override it with RPC_URL for the chain and AIOUM_NODE_PORT for the node software, then point the demo at the new address with NODE_URL (see offchain/src/config.ts and offchain/src/node/server.ts); the facilitator always listens on 8547. A fresh start: restart anvil, then repeat Steps 2–5.

One-shot (background) variant

Once you have seen the pieces separately, the same run fits in one terminal:

cd AIOUM/offchain
anvil --silent &                         # terminal-free
npm run deploy
npm run node &  npm run facilitator &
sleep 4
npm run demo

The node you just ran sold one built-in tool at one price.

Next: Node quickstart, no code — a selling node from one JSON file and a Docker command, with your API behind it.

Node quickstart — bring your API, get paid (no code)

The demo node staked, listed one built-in tool and settled three paid calls. Now a node that sells your API, model or data, from a JSON file and a Docker command, with no TypeScript and no changes to the repo: ten minutes from "I have an API" to agents paying you per call. Every step is the shortest thing that works, on the local development network or the AIOUM network; wallet setup, pricing, the AI-assistant path and the operator playbook in full: Sell a service.

1. Describe your services (one JSON file)

One file, services.json, describes a node. Assemble it from the gallery or write it by hand:

cd offchain
npm run templates -- add weather-open-meteo jina-reader --out services.json   # from the gallery…
cp services.example.json services.json                                       # …or by hand

The template gallery holds ninety tested listings, most of them crypto (feeds, DEX quotes, token data, RWA, prediction markets, chain reads, social bots), and the app's Earn page assembles them in a browser. Each entry is a service with its own on-chain listing, price and stake, and one or more tools built from adapters, the bridge between what you have and what an agent can pay for:

A complete service is a few lines. This one resells a weather API at a fraction of a cent per call:

{ "services": [{
    "key": "weather",
    "category": "data:weather",
    "priceUsdc": 0.002,
    "tools": [{
      "type": "rest",
      "name": "current",
      "url": "https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true",
      "responsePath": "current_weather"
    }]
}]}

Secrets never go in the file. Write "x-api-key": "env:MY_UPSTREAM_KEY", set MY_UPSTREAM_KEY in the environment, and the node refuses to boot if it is missing. Responses are hashed into the results transcript like any built-in tool, so a resold API is verifiable automatically.

Once the listing is live, agents that find their own tools see what yours does and costs in their marketplace search, call it within their budget, and rate you on-chain after every settled session, so a healthy upstream and a tight responsePath earn you the next call.

2. Configure the node

The node is configured through .env:

cp .env.example .env    # then set:

RPC_URL is your chain RPC; on the local development network, http://host.docker.internal:8545. The operator key is OPERATOR_PRIVATE_KEY, or better OPERATOR_KEYSTORE_FILE + OPERATOR_KEYSTORE_PASSWORD_FILE, encrypted at rest. The node signs every transaction with that key, and on the AIOUM network refuses to start without one of the two; on the local development network omit it and Anvil's test accounts are used. AIOUM_NODE_TOKEN is the bearer token for the operator control plane (/settle, /metrics): set it before exposing the node publicly.

The last piece is deployments.json, the contract addresses for your chain, next to docker-compose.yml. On the AIOUM network that is its published deployments.json, the file npm run deploy writes and Deploying the contracts publishes; on the local development network it is the one npm run deploy wrote. The container mounts it read-only, and the node refuses to boot without it.

Every other setting (rate limits, settlement retries, HA, relay, privacy jitter) is listed with its default in the operator configuration reference. The operator wallet needs the ZAI it stakes of its own (stakeZai per service, at least 100; the listing is live at 10,000 total, own plus what backers delegate) and a little gas; on the local development network both are auto-minted.

3. Run it

docker compose up -d          # builds the image, mounts services.json, persists /data
curl -s localhost:8546/health # staked? RPC reachable? → ok:true

Without Docker, AIOUM_SERVICES_CONFIG=./services.json npm run multinode does the same. If the container exits immediately, the log names the missing file.

From here the node carries the whole job, per service: it stakes (minting first on the local development network), registers your identity and the on-chain listing, serves x402-gated calls, records transcripts and anchors results roots, settles earned receipts durably (crash-safe, fee-bumped), and prunes expired evidence at every boot. You watch /health and your balance.

4. Operate it

Scaling out (HA). The catalogue runtime (npm run multinode, the Docker image's command) is one instance per operator key: it takes a PID lock on its data dir at every boot and has no settle lease, because two settlers on one key fight over nonces. Shared-store mode belongs to the single-service runtime, npm run node (src/node/server.ts): set AIOUM_STORE=sqlite, give each instance its own AIOUM_NODE_PORT, and the instances share one receipt/transcript database. A receipt accepted by any instance raises the floor for all, the anchored results root covers every instance's calls in one canonical order, and a TTL settle lease elects the single settler: kill the leader and a peer takes over within AIOUM_SETTLE_LEASE_MS, which npm run demo:ha verifies live.

Monitoring. GET /metrics serves Prometheus metrics (bearer-gated when the token is set): calls served, 402s, upstream errors and unsettled-receipt exposure, how many sessions hold a receipt you have earned and not yet collected. /live and /health are for orchestrators.

State. Everything the node must not lose lives in the /data volume: receipts are earned money and transcripts are evidence. Back it up, never share it between instances, and wipe it when you reset the local development network, because session ids restart.

Prices and splits. Edit services.json and restart. Listings are idempotent: on boot the node reuses your live listing in the same category and registers one only if none exists; a changed split is written on-chain with setServiceSplit. A new price changes what the node charges and advertises in /services, but the on-chain pricePerCall stays as first registered; the node calls updateService only to mark a listing inactive when you remove it with DELETE /admin/services/:key.

Troubleshooting

Between docker compose up and ok:true the node staked, took an identity, listed each service and started settling.

Next: Run a service node — what the node does on every boot, seen from the contracts, and the choices that are yours.

Run a service node

Your node staked, registered an identity and listed your services on its own. Underneath, the runtime in offchain/src/node/ acquires stake, then serves and settles calls; its contract calls show what each boot line means, what your stake buys, and which decisions are yours: the category, the descriptor, the price, the accepted assets and your stakers' split. A service node turns an MCP tool server, a resold API or a model into a live on-chain listing that agents find on their own and pay per call.

The runtime is idempotent: on every boot it brings the operator online (stake, identity, service) only if it is not already, so restarts against a configured chain are free. ZAI is used only to stake (securing the node, slashable) and to govern the DAO; calls are paid in stablecoins or ETH (USDC by default), and you receive the session asset on settlement, never ZAI.

Prerequisites

You need Node 22, the off-chain dependencies (npm install in offchain/), a funded operator key, and a running chain with the protocol deployed. On the local development network the operator key is Anvil account index 1 (mnemonic test test test test test test test test test test test junk), derived by signer(ROLES.operator, …) in src/config.ts, so no private key is hardcoded. The chain is the one from Try it on your computer:

# in offchain/
anvil                 # terminal 1 — chainId 31337, RPC http://127.0.0.1:8545
npm run deploy        # terminal 2 — deploys the stack, writes deployments.json

npm run deploy writes offchain/deployments.json with every contract address, the chainId and the usdc address (mock USDC on the local development network); the node loads it via loadDeployments(). On the AIOUM network the protocol is already deployed: point the runtime at the network's RPC and its deployments.json instead of Anvil.

1. Acquire and stake ZAI

Stake is what makes a stranger's agent willing to pay you. Two floors: you put up at least minSelfStake of your own to list, and the node is live, taking paid sessions, once its total stake, yours plus what backers delegate, reaches minNodeStake. The deploy script sets these parameters (read the live values from the contract):

Staking is a two-step ERC-20 flow against StakingManager: approve, then stake(amount).

// StakingManager.sol
function stake(uint256 amount) external;            // pulls ZAI via safeTransferFrom
function selfStakeOf(address operator) external view returns (uint256);
function totalStakeOf(address operator) external view returns (uint256); // own + delegated
function isOperator(address operator) external view returns (bool);   // selfStake >= minSelfStake
function isActiveNode(address operator) external view returns (bool); // isOperator && total >= minNodeStake

The bootstrap (setupNode() in src/node/setup.ts, the stake step in src/node/stake.ts) does this for you. With no own stake yet it stakes AIOUM_SELF_STAKE; unset, it stakes the full 10,000 when your wallet holds that much, so the node is live at once, else 100, and tells you what comes next:

[node] staked 100 ZAI of your own; the listing goes live once total stake reaches 10,000 ZAI (request backing from the network's staking node, or delegators); own 100 ZAI · total 100 ZAI now

An operator already at the target is left alone ([node] already staked: own 10,000 ZAI · total 10,000 ZAI: live), which makes restarts cheap and safe. To add more of your own later, set AIOUM_SELF_STAKE to the new amount and restart, or stake by hand.

2. Register identity (ERC-8004)

With stake in place, the node needs a name on-chain: an ERC-8004 identity, required before it can list a service. IdentityRegistry.register takes a metadataURI (an off-chain descriptor, typically ipfs://…) and is one per account.

// IdentityRegistry.sol
function register(string calldata metadataURI) external returns (uint256 id);
function isRegistered(address account) external view returns (bool);

Bootstrap registers ipfs://aioum-demo-node only if isRegistered(operator) is false:

if (!(await identity.isRegistered(operator))) {
  await (await identity.register("ipfs://aioum-demo-node")).wait();
}

3. Register a service

A service is the on-chain catalogue entry agents pay against and the listing their marketplace search returns. It is registered on ServiceRegistry, which requires an operator as caller: own stake at minSelfStake. The listing is live once the node's total stake reaches minNodeStake.

// ServiceRegistry.sol — caller must pass staking.isOperator(msg.sender)
function registerService(
    string  calldata category,        // e.g. "mcp:demo-tools", "llm:gpt-oss-120b"
    string  calldata descriptorURI,   // MCP manifest / endpoint descriptor (often ipfs://)
    uint256          pricePerCall,    // in the settlement asset's smallest unit
    address[] calldata acceptedAssets // must be non-empty
) external returns (uint256 serviceId);

The Service struct stored on-chain (and returned by getService) is:

struct Service {
    uint256 id;
    address operator;       // holds the own stake floor; the listing is live at the node floor
    string  category;
    string  descriptorURI;
    uint256 pricePerCall;
    bool    active;
}

These four values are yours to decide. category is the routing and discovery key; the demo uses "mcp:demo-tools", and an agent finding its own tools finds your listing by what it does, so name what you sell. descriptorURI is where agents fetch your manifest; the demo uses "ipfs://demo". pricePerCall is in the settlement asset's smallest unit: the demo charges 1 USDC = 1_000_000 (USDC has 6 decimals), the same unit voucher cumulativeAmounts and on-chain settlement use. acceptedAssets is the non-empty list of assets you accept; the demo passes [deployments.usdc].

You may also declare a model, surfaced off-chain via /services (and in tools/list / /health) so agents can route on it. It is an operator claim, not a proof, and is not recorded on-chain; only descriptorURI is.

You can also set your stakers' split: settlements pay the global delegatorShareBps (10%) to your delegators by default, and you may override it per service with PaymentManager.setServiceSplit(serviceId, delegatorShareBps), which only the service's operator can call. The protocol fee is global and outside operator control; only governance changes it (step 5).

ensureService(...) is idempotent: it scans servicesByOperator(operator) and reuses any live service in the same category; only if none matches does it call registerService(...), then caches the new serviceId from the ServiceRegistered event, falling back to a post-tx operator scan:

const existing = await serviceRegistry.servicesByOperator(operator);
for (const id of existing) {
  const svc = await serviceRegistry.getService(id);   // [id, operator, category, descriptorURI, pricePerCall, active]
  if (svc.category === "mcp:demo-tools" && svc.active) return BigInt(svc.id); // reuse
}
// else registerService(...) and read serviceId from the ServiceRegistered event

4. Start the node runtime

The three steps above run when you start the node:

# in offchain/, with anvil + npm run deploy already done
npm run node

This runs src/node/server.ts: first setupNode(), the idempotent stake / identity / service bootstrap of steps 1–3, under a NonceManager-wrapped operator signer so the bootstrap transactions never collide on a nonce; then an Express server on port 8546 exposing:

• GET /health → readiness: { ok, operator, serviceId, role, blockNumber, selfStake, totalStake, minSelfStake, minNodeStake, live, staked }; 503 until the node is live (own stake at minSelfStake, total stake at minNodeStake) or when the RPC is unreachable, with a hint saying what would make it live (GET /live → { ok, operator, serviceId } is the bare liveness probe)
• GET /services → [{ serviceId, category, descriptorURI, pricePerCall, acceptedAssets }]
• POST /mcp → JSON-RPC 2.0 (tools/list, tools/call); tools/call is payment-gated.
• POST /settle → queues the latest stored voucher for settlement; the settlement loop submits it on-chain.

A clean boot logs:

[node] staked 10,000 ZAI of your own; own 10,000 ZAI · total 10,000 ZAI: live
[node] registering identity
[node] registering service
[node] service ready: id=1 category=mcp:demo-tools pricePerCall=1000000
[node] runtime listening on http://127.0.0.1:8546

On a restart against the same chain those lines become already staked / identity already registered / reusing existing service, and no duplicate state is created.

5. Serve calls and settle

The node is listed; the rest is the life of a session (mechanics: the MCP server guide). An agent opens a prepaid session against your serviceId (gaslessly, for example, via the facilitator, which relays an EIP-3009 authorization), locking a deposit in PaymentManager. For call n the agent signs an EIP-712 PaymentVoucher(sessionId, cumulativeAmount), the receipt under its on-chain name, with cumulativeAmount = pricePerCall * n, and sends it under params.payment of a tools/call. Your node verifies the voucher on-chain, runs the tool, returns the result, and stores the latest voucher. You redeem it with POST /settle { sessionId }, which calls:

// PaymentManager.sol — only the session's operator may settle
function settle(uint256 sessionId, uint256 cumulativeAmount, bytes calldata signature) external;

Settlement splits the gross: a 5% protocol fee to the treasury (global; governance-settable), the delegator share to your stakers, the remainder to you, and any unspent deposit back to the client. The delegator share is operator-chosen per service (setServiceSplit, default 10%); only the protocol fee is outside your control.

Settle on demand (POST /settle) or leave it to the background settlement loop. Settling is your responsibility: idle past the inactivityTimeout (1 day) without settling and the client can reclaim(...) the unspent deposit, the liveness backstop. Settlement also closes the loop with the buyer: once the session settles, the agent that paid you rates you on-chain, 0–100, from what it saw, and errors and slow answers cost points. That rating sits beside your stake and price when the next agent searches, so serving well is how you get found again.

Operational notes

Every runtime setting (auth, rate limits, settlement retries, HA, privacy jitter) is listed with its default in the operator configuration reference. Four things to understand before you run for real.

Capacity scales with total stake. Live needs minNodeStake in total; the number of concurrent sessions you may serve is bonded on top of it:

// StakingManager.sol
function maxConcurrent(address operator) external view returns (uint256);
// = 1 + (totalStakeOf(operator) - minNodeStake) / tokensPerSession   (0 unless live)

With 10,200 ZAI behind the node (AIOUM_SELF_STAKE=10200, or 100 of your own and 10,100 delegated) and the parameters above (minNodeStake 10,000, tokensPerSession 100), that is 1 + (10200 - 10000)/100 = 3 concurrent sessions; 50,000 ZAI allow 401. More stake, yours or delegated, raises capacity; delegators earn the delegatorShare of your settlements in return.

The latest voucher per session is persisted. The runtime keeps only the latest voucher per session (each supersedes the last), writes it to disk under AIOUM_NODE_DIR and reloads it on boot, so a crash never strands vouchers you have earned. The settlement loop drains a durable pending-settle queue with fee-bumped retries until the transaction is mined. On-chain session.spent is the source of truth for what has been paid out; the stored voucher guards against replaying an already-served one (MCP guide).

One node, one signer. All writes go through the single NonceManager-wrapped operator runner. Never run two node processes on one operator key; they fight over nonces. Shared-store mode is the way to run several instances under one key.

Idempotency is per-category. ensureService reuses a live service matching its hardcoded category ("mcp:demo-tools"). To list a different service, register it explicitly with your own category / descriptorURI / pricePerCall / acceptedAssets.

That is the whole node, from stake to settlement.

Next: Resell fal.ai models — one adapter in full: an image, video or audio model as a paid listing.

Run a planner node

A planner is the model an agent thinks with: every turn, the runner sends it the conversation so far and the tools it may call, and it answers with the next call or the final answer. On AIOUM nobody owns the planners. A planner is a listing like any other, served by a node, paid per turn from the agent's budget, picked by the runner for its quality and price. This page is for the person running one.

Who can run one

Any node, on any machine, with one of three things behind it:

• A key to a hosted model. The gallery holds a planner template for each of the common ones: planner-openai, planner-xai, planner-gemini, planner-mistral, planner-cohere, planner-groq, planner-together, planner-fireworks, planner-deepinfra, planner-cerebras, planner-openrouter. The key stays on your node; the buyer sees a price per turn, never the key.
• A model on your own machine. planner-ollama (Llama 3.2) and planner-ollama-qwen (Qwen 2.5 7B) run on Ollama beside the node: no key, 8 GB of memory or more, a GPU welcome. The node downloads the model the first time it serves.
• A model on a server or a rented GPU. Anything that speaks the OpenAI chat API (vLLM, Ollama on a GPU box, TGI, a cloud endpoint) is a planner: a template with its address in baseUrl, or planner-ollama pointed at the server. The network's own test planner on Base Sepolia is Qwen 2.5 32B on a rented GPU, listed this way.

Not a planner: a chat listing (llm:*, the "An AI model I can reach" and "A model on my computer" cards). Those sell a chat tool for agents to call as a tool; the runner plans only with a listing in a planner:* category whose tool is plan. Nor a Claude subscription: a person's plan plans their own agents on their own runner and is never sold.

What you get

• Paid per turn, at the price you set, from the budget of the agent that planned with you, settled on chain like every other call: 85% to you, 5% to the protocol, 10% to the people who staked behind your node unless you set the stakers' share otherwise. A planning turn carries the whole conversation and the tool list, so your own cost per turn grows as a job goes on; price for it.
• Demand from three places. Every person on a shared runner plans with marketplace planners only, since a shared runner never lends its own key or plan to the people on it. A runner whose own planner is out (a plan at its limit, a key without credit) falls through to the best live listing. And when a project proposes its stages, the proposal is a planning turn too.
• Ratings that follow the listing. Every paid turn leaves an experience record on the directory, signed by the paying runner and checked against the session on chain; the model picker shows your rating and how often your turns worked.

How the runner picks

For a Super Agent, in this order: the model's tier (frontier, 70B, 7B, 3B, read from the model id), then the kind within a tier (the person's own Claude plan first, then a listing, then the runner's own key, then a local model), then the price, then the name. When a person's own planner is out, the fallback is the best live listing by tier, then price, then name. A rating and the experience record decide the order in the manual picker and the labels on it; the automatic pick goes by tier and price. A better model at a fair price is picked; a cheap small one is picked when nothing better is live.

Stake and the rest

A planner listing needs what any listing needs: 100 ZAI of your own stake once per operator, a 100 ZAI bond per listing (back after 14 days when you take it down), 10,000 ZAI of total stake for the node to be live (the backer pool delegates the gap after a review), and 100 ZAI per concurrent session above that. On the testnet the faucet gives 1,500 ZAI and 50 zUSD once per wallet; your node claims them on Launch → Your node.

List one

Launch → A service → Your node → Sell: pick a planner template, give its key or its address, set the price per turn, test one turn (the test sends a short conversation), go live. The listing appears in the Planners group on Earn and in every runner's model picker within a minute.

The Supernode

The node you install with one command is one program: your private node, with your own runner inside it and a selling node beside it. It holds your accounts, keys, files and, when you want one, a local model; your agents run in it and pay from its wallet; what you list on it earns per call. A local model on it can be listed as a planner and earn while it idles. Several machines are several nodes, each with its own operator wallet, stake and bond; the app works on the one you pick.

.ii names

A name on the network is a token you own for a year at a time. dogs.ii is the label dogs, and it resolves to what an agent needs to reach you: a payment address, the node you run, the listing you sell, and text records by key. Anyone can pay dogs.ii or hire dogs.ii; the chain holds the name and the records, so no registrar, server or directory stands between a name and its owner.

What a name resolves to

Ownership transfers as any token; the records stay with the name until its new owner changes them.

Buying and renewing

A label is three to thirty-two characters of a-z, 0-9 and hyphens, no hyphen first or last. The price buys the name for a year and is in ZAI by length; a renewal year costs the same (governance can set renewals apart). The ZAI goes to the treasury.

Anyone may pay a renewal, one to ten years at a time, and it runs on from the current term's end. Past its end a name stops resolving; for ninety days more only its owner can renew it, and after that anyone can buy it anew (the old token is burned and the records start over).

Governance keeps labels back (reserve) and hands reserved or short names out itself, which is how trademarks and premium names stay out of open minting. A pause stops minting; what is minted stays.

Buy on the app's Names page (approve the ZAI, then register; renew there too), or from code: IINames.register(label) after ZAI.approve(names, priceOf(label)), and IINames.renew(label, years).

Reading a name

aioum name dogs.ii        # owner, payment address, node operator, listing, term — or free, and the price

In code: resolveName(pub, cfg, "dogs.ii") from @aioum/sdk (viem), resolveName(dep, provider, "dogs.ii") from the off-chain SDK (ethers), and payeeOf(…, "dogs.ii") for the address a payment to it goes to. The subgraph carries every name (names, nameTexts) for any front-end to read.

Where it lives

src/registry/IINames.sol, deployed with the rest of a network (deployments.json → names) or added to a live one with AIOUM_DEPLOY_ONLY=names. On Base Sepolia: 0xC0FdF08B0529df6333511C0bCE8b626bd50c974b.

Resell fal.ai models — a one-click media node

fal.ai hosts 1,000+ production generative-media models (FLUX, Kling, Veo, Whisper, …) behind one API key, billed per output. AIOUM's fal adapter turns any of them into a paid, verifiable AIOUM service: agents find your listing on their own and pay per call in USDC with receipts against escrow, you pay fal for the compute, and the spread is your margin.

fal sells inference with accounts, cards and quotas, built for humans and companies; you open the account, add the card and guard the key once, and every agent on the marketplace is spared it. AIOUM sells trust between strangers: machine-speed micropayments, staked delivery guarantees, no signup. The adapter bridges the two: fal's catalogue becomes supply an agent buys mid-run with nothing but its budget, and every response is hashed into your results transcript, so "did the model actually run?" is arbitrable like any other AIOUM call.

1. Get a fal key

Create an account at fal.ai, add credits, and generate a key. Export it:

export FAL_KEY=key_id:key_secret

2. Add a service entry

Everything else is one entry in services.json (see the node quickstart for the full node setup):

{ "services": [{
    "key": "fal-image",
    "category": "media:image-gen",
    "priceUsdc": 0.05,                      // your price — set it above your fal cost
    "model": "fal-ai/flux/dev",
    "tools": [{
      "type": "fal",
      "name": "generate",
      "model": "fal-ai/flux/dev",           // any model slug from fal.ai/models
      "responsePath": "images.0.url"        // dot-path into the result; omit for full JSON
    }]
}]}

That is the whole integration. Tool args go to the model verbatim, {"prompt": "a lighthouse at dusk"} for FLUX, exactly as fal's model page documents. The result (here the hosted image URL) returns to the paying agent, hashed into the transcript. An agent that needs an image and may find tools on its own meets this listing in its search, price included, and calls it in the same run.

3. Long jobs: queue mode

Video, training and other slow models should use fal's queue API rather than a blocking request. It matters beyond timeouts: an agent rates you after every settled session, and slow answers cost points. Set mode: "queue" and the adapter submits the job, polls until COMPLETED, and fetches the result:

{
  "type": "fal",
  "name": "generate",
  "model": "fal-ai/kling-video/v2/master",
  "mode": "queue",
  "responsePath": "video.url",
  "timeoutMs": 300000                       // total budget incl. polling (default 5 min)
}

Spec reference

Every field the fal tool type accepts, with its default:

Pricing your margin

fal bills you per output (~$0.025 per FLUX [dev] megapixel-image, more for video); you charge priceUsdc per call. Set yours above the model's current fal price; fal cost × 1.5–2 is common, paying for stake exposure, gas, and the premium of signup-free access. Failed upstream calls throw before settlement, so agents pay only for served responses; and since the paying agent rates errors as well as speed, a model that fails often costs rating as well as revenue.

The fine print

You are the operator of record. The fal account, its terms, and its content policy obligations are yours; AIOUM only meters and settles the calls.

Outputs are URLs on fal's CDN. The transcript proves which URL you returned, not that the file behind it persists, so mirror outputs you may need for a dispute.

One key, many models. Add one tool per model under as many services as you like; each service has its own price, its own on-chain listing and its own rating from the agents that use it.

Media is one kind of supply an agent buys mid-job. The other is the open web, and two web-data platforms fit behind the same one-line pattern.

Next: Resell web data: Apify & Bright Data — scrapers, search results and datasets as paid listings, from one line of config.

Resell web data — Apify and Bright Data

The open web follows the same one-line pattern as media models: a key in the node's environment, a price above the upstream's, and you as operator of record. Two platforms sell it as a service: Apify (20,000+ ready-made scrapers and automations) and Bright Data (web access past bot detection, search results as data, structured datasets for major sites). The apify and brightdata adapters turn either into paid AIOUM tools from one line of config, exactly as the fal.ai adapter does for media models, and an agent with one AIOUM budget reaches both through you.

What they are

Apify is a marketplace of Actors: serverless programs, mostly web scrapers and browser automations (Google Maps places, Instagram profiles, Amazon products, a generic site crawler, thousands more), each with a JSON input and a dataset of JSON items as output. Pricing is per event (result item, run or compute unit), set by each Actor's author. The API returns an Actor's dataset in one call when the run finishes within 300 seconds, or as an asynchronous run you poll. Since 30 June 2026 Apify also accepts x402: an agent pays USDC on Base for a prepaid token (minimum 1 USD, valid 14 days, non-refundable) and uses it as a bearer token with no Apify account (announcement, docs).

Bright Data is a web-data platform on a large proxy network. What matters here: the Web Unlocker API (any public page, with bot detection, CAPTCHAs and proxy rotation handled, optionally as markdown), the SERP API (Google, Bing and other search results as structured data), the Web Scraper API (structured records for 100+ sites, each a dataset you trigger with URLs or search terms and download when ready), and a Browser API. It ships an MCP server with 60+ tools and a free tier of 5,000 credits a month across those APIs (overview, MCP server, API docs).

To an agent the two do one job: turn a question into fresh web facts. It searches ("who sells X near Y"), reads ("what does this page say", past the bot wall) and extracts ("this product's price, rating and stock as JSON"). Both already sell directly to agents, so why resell them through AIOUM at all?

Why resell them through AIOUM

A Coinbase wallet can pay Apify directly; an MCP client can call Bright Data directly. Reselling through your node is not a shorter path but a different offer. The buyer's agent holds one capped session key and pays your node, Apify- or Bright-Data-backed, from the same escrow it uses for every other service: no prepaid token or API key per vendor. Your stake backs the result: unspent escrow refunds, and a wrong result is disputable with an anchored transcript, where a prepaid token is spent whether or not the Actor delivered. You choose which Actors and zones to expose, name them for agents (data:places, data:web-fetch), set a per-call price, and absorb the upstream's per-event billing; that margin is the business. A buyer who wants distance from you reaches you through a bonded relay, so the vendor sees your key and never the buyer.

Naming matters, because agents find listings on their own. An agent searching mid-run describes what it needs in plain words and reads your listing's category, tool name and description; the rating it leaves at settlement is what the next search ranks by. A clear description with example args gets you found; fast, correct answers keep you well rated.

You are the operator of record with the upstream: their terms, and the target sites' terms, apply to you.

The apify adapter

Tool args are the Actor's input, verbatim; an optional input supplies static defaults the args override. Two modes match the two ways Apify runs an Actor. sync, the default, calls POST /v2/acts/{actor}/run-sync-get-dataset-items with clean=true&format=json: one request, dataset items back when the run finishes. Apify cuts it off at 300 seconds with a 408, so use it for Actors that finish in a minute or two. async calls POST /v2/acts/{actor}/runs, polls GET /v2/actor-runs/{id} until SUCCEEDED (failing on FAILED, ABORTED, TIMED-OUT), then downloads GET /v2/datasets/{defaultDatasetId}/items: the mode for crawls and anything that takes minutes.

{ "key": "apify-maps", "category": "data:places", "priceUsdc": 0.05,
  "tools": [{
    "type": "apify", "name": "search",
    "actor": "compass~google-maps-extractor",           // id or username~actor-name
    "input": { "maxCrawledPlacesPerSearch": 10 },       // static defaults; args override
    "limit": 10,                                        // max items returned
    "description": "Google Maps places for a search + location. Args: {\"searchStringsArray\":[\"coffee\"],\"locationQuery\":\"Lisbon\"}"
  }]
}

Set APIFY_TOKEN in the node's environment. The adapter needs only a bearer token, so it can be one bought from Apify over x402 with no account: an Apify-backed node runs from a wallet alone.

The brightdata adapter

Two modes again, matching Bright Data's two shapes of API. unlocker, the default, calls POST /request with { zone, url, format } synchronously. The zone is a Web Unlocker zone (any page) or a SERP API zone (search results); with a SERP zone the url is the search engine URL and &brd_json=1 asks for structured JSON. format: "raw" returns the page as delivered (dataFormat: "markdown" for markdown); format: "json" wraps it as { status_code, headers, body }. scraper calls POST /datasets/v3/trigger?dataset_id=… with a JSON array of inputs (one from the tool args, or several from an inputs array in the args), polls GET /datasets/v3/progress/{snapshot_id} until ready (failing on failed), then downloads GET /datasets/v3/snapshot/{snapshot_id}?format=json.

{ "key": "brightdata-unlock", "category": "data:web-fetch", "priceUsdc": 0.004,
  "tools": [
    { "type": "brightdata", "name": "fetch",  "zone": "web_unlocker1", "dataFormat": "markdown",
      "description": "Any public page as markdown. Args: {\"url\":\"https://…\"}" },
    { "type": "brightdata", "name": "search", "zone": "serp_api1",
      "url": "https://www.google.com/search?q={q}&brd_json=1",
      "description": "Google results as JSON. Args: {\"q\":\"…\"}" }
  ]
}

Pricing and the fine print

Price above cost. Apify bills per event (often per result item), Bright Data per request or record; check the Actor's or zone's rate and set priceUsdc above it plus your share of settlement gas. At the default split you keep 85% of the price (selling agent guide).

Results are evidence. Whatever the tool returns is hashed into the session transcript and can be anchored on-chain. Raw HTML makes a large entry, so prefer markdown (dataFormat), a responsePath or a limit: buyers get what they need and your transcript store stays small. Retention is AIOUM_TRANSCRIPT_RETENTION_MS.

Timeouts hurt both sides. A call that times out is refused and not charged, but the agent waited, and errors and slow answers cost you points in the rating it writes on-chain at settlement. Match mode to the job: sync for seconds, async or scraper for minutes.

Compliance is yours. Apify's and Bright Data's terms, KYC for some Bright Data zones, and the target sites' terms all bind the operator of record. Do not resell data you may not.

The adapter test suite covers both against a local mock upstream (cd offchain && npm run test:adapters, 19 cases), so you can change them without a real key.

The other direction: paying x402-native APIs from an AIOUM budget

Apify's x402 uses the Coinbase scheme: the agent signs a USDC transfer authorization on Base per payment and buys a prepaid token. AIOUM's agents sign receipts against escrow, a different primitive with different guarantees (x402 walkthrough): one escrow session, one signature per call, a stake behind every result. Your node is the bridge. The buyer's agent spends its one AIOUM budget on your node; your node pays the upstream with its own key or prepaid token, and the agent never needs to know which vendor stands behind the answer.

Other upstreams worth adding

Most keyed HTTP APIs need no new adapter: the generic rest adapter covers Tavily, Serper and Exa (search), Jina Reader (page to text), ElevenLabs (text to speech), and any REST endpoint with a URL, headers and a responsePath. A dedicated adapter earns its place when the upstream has a job pattern to hide, as fal, Apify and Bright Data do (Replicate's polled predictions and Firecrawl's crawl jobs are the same shape). To request one, open an issue with the API shape and a mock response; an adapter is a small, tested addition.

Every one of these listings works the same way: your node holds a vendor's key and sells calls against it to strangers. Right for public services; wrong for your own mail, calendar and notes, which no stranger's node should ever hold.

Next: Integrate your service directly — the provider's own path: the OpenAPI spec you already publish, one node on your infrastructure, your domain as proof, agents as buyers.

Integrate your service directly

You run an API and publish its spec. That spec is the whole integration: one command turns it into listings, one command runs a node on your own infrastructure, one record on your domain marks the listings as yours, and agents buy from them per call, paying before you serve. Your key never leaves your node; you open no accounts for your buyers and send no invoices.

1. Import the spec

git clone https://github.com/oum-dev/aioum && cd aioum/offchain && npm ci
npm run templates:generate:openapi -- https://api.example.com/openapi.json --name example

OpenAPI 3.x or Swagger 2, JSON or YAML. Every operation becomes a tool on a rest listing: path and required query parameters are its inputs, optional ones ride only when an agent gives them, a JSON or form body comes from the request schema's required fields, and the whole reply goes back. The spec's securitySchemes become the key your node reads from its environment, EXAMPLE_API_KEY for an API key or bearer token, EXAMPLE_BASIC_AUTH for basic auth. Operations group by tag, one listing each, priced from the family's floor (--category data is the default; --price sets one price for all). Sample inputs come from the spec's examples, defaults and enums; give the rest with --sample latitude=52.52 or --samples file.json. An operation whose required input has no value, needs an OAuth login or uploads a file is left out and named, so nothing goes live that cannot answer.

It writes openapi/example/<listing>.json, one per listing to read through, and openapi/example/services.json, the file a node runs on. Each listing carries "provider": { "domain": "api.example.com" } (the spec's server host; --domain overrides, --no-domain omits) and "verified": false until one real call has passed:

AIOUM_TEMPLATES_DIR=./openapi/example npm run templates -- verify example-pets

The app does the same on its Earn page: Import an OpenAPI spec, the spec's URL, one row per operation with a box and a price per listing, one field for the key, a test call, Go live now on the node on that machine.

2. Set prices

priceUsdc per listing in services.json, or let a listing follow demand: "pricing": { "base": 0.002, "max": 0.01 } raises the price a step at a time while calls queue and lowers it when they stop (Sell a service). Agents compare prices at every call, so a fair price wins calls and a busy one tells you to add capacity: a second node on the same file.

3. Run one node on your infrastructure

# .env at the repository root
RPC_URL=…                                    # the network's chain, with CHAIN_ID
OPERATOR_PRIVATE_KEY=0x…                     # the key that stakes, lists and settles: yours
EXAMPLE_API_KEY=…                            # what the spec's auth needs
DOMAIN=example.com                           # the node answers at https://node.example.com
AIOUM_INDEXER_URL=https://indexer.<network>  # the network's directory, as the app shows it under Your network

scripts/deploy-network.sh install
SERVICES=multinode AIOUM_SERVICES_CONFIG=$PWD/offchain/openapi/example/services.json scripts/deploy-network.sh deploy

With the network's deployments.json in offchain/ (the network's app serves it at /api/deployments), deploy writes one unit, aioum-multinode, behind TLS at node.example.com. On boot the node stakes the operator's ZAI, registers each listing on-chain and serves it, then announces https://node.example.com to the directory. The directory asks the node to sign a challenge with the operator key before it maps your listings to that URL, and probes it from then on; nobody edits a list by hand. scripts/deploy-network.sh status shows the unit and its health, logs multinode follows it.

4. Prove the domain

npx aioum sell verify-domain api.example.com

Prints the two records that mark a listing as first-party, either one enough: a DNS TXT record aioum-verify=<your operator address> on the domain, or https://api.example.com/.well-known/aioum.json with { "operators": ["0x…"] }. Add one, run the command again: verified. The directory checks on every refresh, the listings show Official on the marketplace and on their pages, and official listings rank first among live ones. Anyone can run a copy of a listing from the same template; only yours carries the mark.

5. Get backed, if you need to

A listing takes paid calls once 10,000 ZAI stand behind its operator. Stake it yourself, or put up 100 ZAI of your own and ask the network's staking node for the rest: npx aioum stake request <serviceId>, or Request stake on the listing's page. The review makes your sample call through your node and reads the listing against a short rubric; on a yes the pool delegates within seconds (Stake on an operator).

6. Watch demand

Every listing's page and card read "price up 25% today · 340 calls/h · 3 operators serve this"; npx aioum service <serviceId> prints the same record, and the directory's GET /services/:id/demand has the price trail and the last settled sessions. A price that keeps climbing is demand your node cannot absorb: add a node, or let the price stand.

What you earn

Buyers deposit before the first call and sign a receipt per call; your node settles once per session and the contract pays you in USDC, the backers their share, the network its fee: at the default split you keep 85% (5% network, 10% to backers). No invoices, no chargebacks, no card on file anywhere.

How agents find you

The directory carries what an agent reads to choose: your category, the tool descriptions from your spec's summaries, the price, the operator's rating from settled sessions, the stake behind it and the Official mark. An agent searches it on its own mid-run, tries a listing against its rivals and keeps what serves best, so write the spec's summaries for a reader who has one line to decide.

Next: Your private node — a node only your agents call, holding your own secrets on a box you control, with no meter on it.

Private node (your personal runtime)

The marketplace model, a node holds the API key and you pay per call, is right for public services (search, data feeds, DeFi, LLMs) and exactly wrong for personal ones: no stranger should hold your Gmail token. The private node is for those: a small runtime you deploy that holds your secrets (encrypted), exposes them as tools, and is called directly by your agent for private steps, unmetered because you own it. The marketplace never sees your data.

A workflow spans both worlds: public steps go to paid marketplace nodes, personal steps to your private node, local and free. launch-agent-workflow.md runs a whole one end to end.

What it is

An HTTP/MCP-style server (offchain/src/private-node/) with the same tools/list / tools/call shape as a marketplace node, but personal and free. Behind it, an encrypted-at-rest secret store (AES-256-GCM, ~/.aioum-private/secrets.enc): secrets never touch disk in plaintext and never leave the box. In front of it, the connectors: memory, the local brain, and workspace, a folder on the machine your agents work in, both yours with no credentials; gmail / gcal (real Google OAuth behind your own client creds); a generic apikey fallback for any key-only API; and the models, hardware, training, skills, wallet, exchange and account connectors of Your node. Every tool does the thing it names; nothing answers without doing it.

Deploy — local or VPS (one image, both work)

Local is the recommended choice for privacy:

cd offchain
PRIVATE_NODE_PASSPHRASE=your-strong-pass npm run private-node     # binds 127.0.0.1:8770

Loopback only. Every route except GET /health and the OAuth callback (GET /oauth/:provider/callback, where Google redirects your browser back to) needs the node's bearer token. On first start the node writes one to ~/.aioum-private/token (mode 0600) and prints the path, never the token. Callers on the same machine read that file; set PRIVATE_NODE_TOKEN to supply your own. Leave PRIVATE_NODE_PASSPHRASE unset and the node encrypts with an auto-generated 0600 keyfile instead.

For agents that run while you are offline, the same image runs on a VPS, always on:

cd offchain/src/private-node
PRIVATE_NODE_PASSPHRASE=your-strong-pass docker compose up -d      # published on the host at 127.0.0.1:8770 only; Caddy on the same box proxies to it

Beyond localhost, put TLS in front (Caddy/nginx) and give each remote caller the bearer token once. The selling node it starts for you is separate: where it answers is set on the Earn page ("Where your node answers"), behind a relay it dials out to, so this machine's address never goes on chain, or at a direct https address on a server with no domain needed; the node writes it on chain itself with its certificate's fingerprint (going to production). A browser app on another origin needs PRIVATE_NODE_ALLOWED_ORIGIN (default http://localhost:3000).

Connect accounts

Connect the accounts your agent will act through. For Gmail and Calendar, set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET; POST /connect {provider:"gmail"} returns an authUrl, and the callback stores the tokens encrypted (OAuth, not an API key, as with local MCP servers). sendGmail sends through the Gmail API and createGcalEvent creates the event on your primary calendar, each with the stored token, refreshed by the node when it expires. For any key-only API, POST /connect {provider:"apikey", apiKey:"…", baseUrl:"https://…"} stores the key encrypted and fixes where it may go: the call tool resolves its path against that base URL and refuses any other origin. memory and workspace need no connect: the moment the node is up, remember and recall keep and find your context, and ws.write and ws.read put files on your machine and read them back.

An inbox of the agents' own: connect Agent inbox with an AgentMail API key (agentmail.to, free for three inboxes) and name the inbox, and your agents get an address to receive at and send from: agentmail.inbox, agentmail.send, agentmail.messages, agentmail.read, agentmail.reply, and agentmail.wait for the next message to arrive. The key stays in the node's encrypted store, and mail whose content came from the marketplace is not sent without your say, as with Gmail. It opens no accounts anywhere; it is one address.

GET /health lists connected providers (names only, never secrets); GET /connections returns the same with the token, and POST /disconnect removes one.

Your subscriptions and keys

Your Claude plan, your API keys and the keys your node's tools read are set on the node too, under Subscriptions and keys or with aioum subs add. Your own agents plan, judge and write with them; nobody else's can, and they are in no list of tools (Your subscriptions and keys).

Local brain (your context)

The node also remembers for you. The local brain (offchain/src/private-node/memory.ts) is a persistent, capped, user-owned context store of facts, preferences, results and notes, kept on your private node and recalled by keyword (recall). It is exposed two ways. As a memory connector it offers remember / recall tools, so a workflow step reads or writes it like any other tool. As REST endpoints, GET /memory and POST /memory recall and store, DELETE /memory/:id forgets, and POST /forget-all wipes the store in memory and on disk (secrets and schedules untouched); all bearer-token protected, like the rest of the node.

The invariant is data minimization: your context stays on the private node. The orchestrator recalls only the relevant slice for a step and sends only the minimal per-call inputs to marketplace nodes; a paid node gets the bytes its call needs, never your whole context. The store is capped, so it cannot grow unbounded, and encrypted at rest with the secret store's key. In a workflow, memory steps are personal: steps like every private-node step: local, free, never routed to the marketplace.

Backups

POST /export returns the node's encrypted state as one blob under a passphrase you choose (12 characters minimum). Secrets and memory inside stay encrypted under the node's own at-rest key, so restoring on another machine needs the same PRIVATE_NODE_PASSPHRASE or a copy of its .secretkey. POST /restore loads a blob; restart the node afterwards. The bearer token is never included. From the command line:

npm run private-node:backup -- export  ./aioum-backup.bin
npm run private-node:backup -- restore ./aioum-backup.bin

Security model

The scope, plainly: the private node keeps personal data on a box you control. A public marketplace node still sees the request it serves, because it must; what protects you there is trust, stake and reputation, not cryptography. See architecture.md §verification.

How a workflow uses it

The private node runs the workflow itself. Its executor (offchain/src/private-node/executor.ts) calls its own connectors in-process for personal steps and pays marketplace nodes for public steps from the node's budget-capped agent wallet (open session → sign receipt → call → settle), stopping at the budget. A byte cap on data sent to paid nodes blocks a run that ships more context than expected rather than silently truncating it.

Scheduled runs use the same executor: POST /schedule {name, steps, intervalSeconds, budgetUsd} creates a cron job, POST /schedule/:id/run fires it now, POST /schedule/:id/toggle pauses or resumes it, DELETE /schedule/:id removes it, GET /schedules lists them. Jobs persist to disk, each run holds a lease so two ticks never double-pay, and a job that comes due while the node is off for hours is skipped rather than fired in a burst on restart.

You now have a selling node with its catalogue of adapters, and a private node that keeps your own secrets and pays the marketplace from a capped wallet. Each reads its settings from the environment.

Next: Every setting — every environment variable each runtime reads, its default as the code reads it, and what it changes.

Operator configuration reference

A selling node, its adapters and a private node, plus the facilitator, bundler, relay, indexer, billing, deposit service, staking node, agent runner and monitor that complete the stack, are configured through environment variables. Each default is the one the code reads, with the reading file named, so you never open the source to learn a setting. All are optional on the local development network: with nothing set, the stack targets Anvil at http://127.0.0.1:8545 with deterministic test accounts. offchain/.env.example is the copy-and-edit template.

Two files every runtime depends on are not environment variables. deployments.json holds the contract addresses for your chain, loaded from the working directory (offchain/): npm run deploy writes it for the local development network; a live chain uses that network's addresses file (deploying, networks.json). A runtime refuses to start without it; the Docker image mounts it read-only. services.json is the multi-service runtime's catalogue (node quickstart); any header or key written env:NAME resolves from the environment at load time and fails loudly if missing (FAL_KEY for the fal.ai adapter, say).

Booleans are the literal string 1 (or 0 where noted). Durations are milliseconds unless the name says otherwise. Token amounts are base units: USDC has 6 decimals, ZAI and ETH 18.

Chain, keys, and live-chain mode — src/config.ts

Settings every runtime shares: which chain it talks to, which key it signs with, and whether it may behave like a development network at all.

Service node — src/node/server.ts (single service) and src/node/multinode.ts (catalogue)

Where the node listens, where it keeps receipts (vouchers, in the code) and transcripts, who may settle, how much load it accepts, and which environment names the adapters read upstream keys from.

Three services.json fields per listing, beside priceUsdc and stakeZai:

Templates in the gallery (offchain/templates/*.json) add verified (set only by npm run templates -- verify), generated: { source, at } on generator-written ones, alsoOn (other templates serving the same model), local (needs Ollama or Docker on the box), requires: { gpu?, vramGb?, ramGb?, cpus? } (the bootstrap lists it only on a machine that meets it) and hostAccess (Ready-made listings).

Settlement loop — src/node/settle-loop.ts

A crash-safe background loop settles earned receipts on-chain and never drops an entry: past the deadline an entry is parked and retried at a slower cadence until it lands. These settings tune how eagerly it tries and how far fees may climb.

Multi-instance (single-box HA) — src/node/sqlite-store.ts

When one process is not enough, several instances serve the same operator key from one box, sharing state through SQLite and electing one to settle.

Privacy relay — src/relay/server.ts

A relay is an operator whose service is "proxy any other AIOUM service", so a buyer's calls never link on-chain to the node that served them. It shares the node's auth, rate and body settings.

Facilitator — src/facilitator/server.ts

The facilitator relays a buyer's signed payment authorization on-chain so the agent never needs gas of its own. It holds only a gas key; these settings are its guard rails.

Bundler (ERC-4337 relay) — src/bundler/server.ts

The bundler submits smart-account operations for agents that run on session keys, sponsoring their gas within a per-account budget.

Discovery indexer — src/indexer/server.ts

The indexer is the directory behind discovery: it rescans the chain for listings, probes live nodes for their catalogues, and is what an agent searches when it finds tools on its own mid-run. It probes the nodes in its seed list and every node that announced itself: POST /refresh { "nodeUrl": "https://node.example.com" } makes it ask that URL for GET /identity and, when every operator the node claims has signed the challenge, keep the node (nodes.json in its data dir), probe it on every refresh and map to it only the listings of the operators it proved. GET /nodes lists the seeds and the announced nodes. A listing on-chain whose node is neither a seed nor announced has no endpoint in the directory, and no agent can call it.

Each record in /services carries template (from the node, or the listing key when the node is unreachable), pricing and load as the node reports them, and demand: the price change over 24 h, calls per hour with its basis (node: the node's own count of calls served in the last hour; settled: sessions settled on-chain in the last hour, settled amount ÷ the price in force), and how many live listings run the same template. GET /services/:id/demand adds the price history, the last settled sessions and every live copy of the template, cheapest first. A listing whose node reports provider.domain carries provider (domain, verified, method: dns or well-known, checkedAt, detail in plain words) and official: true once the domain names its operator; a verified pair is rechecked after an hour, a failed one after ten minutes. Ranking puts official listings first among the live and reachable; ?official=1 filters to them.

Each record also carries experience: per need (the kind of job, data:crypto, image:gen), what agent runners' runs found with the listing: count (one record per session per tool), okRate (each record weighed by what it paid; a failed call one call at the listing's price), avgJudge (the judge's mean, 0-100, when judged), p50LatencyMs, avgCostUsdc and the latest five notes; GET /services/:id/experience has it per tool with the latest records. Runners post the records to POST /experience, signed with the wallet that paid; the indexer takes one only when the signature recovers to the client of that session on chain, the session is with that service and has settled (an error, which charges nothing, on the open session), the signer is not the listing's operator, and the session and tool are not recorded yet; it keeps them in experience.json, pruned by age and count.

Managed billing — src/billing/server.ts and src/billing/store.ts

Managed billing lets a person pay by card and have an agent's gas and deposits sponsored from that balance; these settings name its admin token, signers and price basis.

Deposit service — src/deposits/server.ts

The deposit service funds an AI wallet from any chain in any major asset: it quotes a route to USDC on this network from the route provider, hands out the wallet's deposit address, keeps the ledger and sweeps what arrives (the conversion fee to the treasury, the rest to the wallet). It starts in one of two modes: route when the provider delivers to this chain, and direct on any other chain, the local development network (chain 31337) among them, where it serves only the deposit address and the sweep of USDC sent straight to it; there /chains, /tokens and /quote answer 501 with "Routes from other chains deliver to Base; on this network send USDC to your deposit address and it is swept to your AI wallet". The fee is depositFeeBps from deployments.json (DEPOSIT_FEE_BPS at deploy).

Staking node — src/backer/server.ts

The network's staking node backs listings so a seller goes live with 100 ZAI of their own: POST /requests {serviceId} starts a review (the listing on-chain and on its node, the operator's own floor, slashes and disputes, the price against the gallery, the pool's cap, a sample call through the node, then a model against the rubric); on a yes the pool delegates the gap to minNodeStake plus headroom, makes one paid call through the node, and the listing is live. A loop re-checks every backed node and takes the ZAI back, with the reason, when the node stops answering, a dispute is raised or the operator is slashed. GET /requests/:id, GET /requests?operator=, GET /health (the pool's balance, what it holds behind operators, the reviewer) and GET /rubric.

Monitor and paymaster tooling — src/monitor/watch.ts, src/tools/paymaster.ts

npm run monitor polls the chain and the services' /health endpoints, exposes Prometheus metrics, and raises alerts. npm run paymaster reports the paymaster's EntryPoint deposit and runway and can refill it.

Deploy, handover, and the safety gate — src/deploy.ts, src/handover.ts, src/verify-deploy.ts

Read once, by the deploy and governance tools, not by the long-running services. You set them in order when deploying the stack.

Private node — src/private-node/*.ts

The self-hosted personal runtime (Your private node) keeps secrets, a local context store and scheduled workflows on your own machine, and pays marketplace nodes from a budget-capped agent wallet.