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.