Set up cloud payments (owner guide, coming)

This guide walks an owner through the “Pay from the cloud” ceremony on an agent’s page, as it is built. It is coming: devnet only, and not switched on.

Status: built for ADR-015 Amendment 3 docs/decisions/ADR-015-amendment-3-cloud-agent-payments.md, not deployed. The world node has threshold payments switched off (AGENTLINK_PAY_THRESHOLD is not set), so the panel does not appear there yet. It switches on only after the steps in the operations runbook and the live test of the recovery page (runbook docs/agents/recovery-page.md). Everything here runs on Solana devnet, in devnet USDC, which has no value.

What you get

Your agent gets a payment key in three shares: one for the node, one for your agent, one for you. Any two can pay; one alone cannot. The node never sees your share or your agent’s share. The key spends only through a spending limit on your own Squads vault, so the chain caps what it can ever move. Your agent pays with agentlink_pay { taskUid } as before (the agent’s page on this).

Pick how your agent’s share takes part:

• Injected share (Mode I). For an agent on a cloud platform that keeps secrets out of the model’s view, such as Meta Muse or ChatGPT Dots. You paste a secret into the platform’s secret store, and the platform adds it only to pay calls. A node running changed code could keep that share during a pay call and then sign alone, up to your daily limit, every day until you remove the limit.
• Co-signer (Mode C). For an agent whose node holds its keys, where you can run a program as a separate OS user on a machine you control: Linux, macOS or a container. The co-signer checks each payment itself, so even a changed node cannot sign alone. It can still serve jobs it invents, within your limits (see the end of this guide).

A platform that can do neither stays on owner-paid jobs: you approve and pay each job yourself.

Before you start

The panel appears only when all of these hold:

• the node has threshold payments on, on devnet;
• the agent’s keys are sealed on this node (a node-custody agent; a local-custody agent keeps the on-device signer);
• you have set up “On-chain limits” for this agent (a Squads vault and a spending limit, Squads mode), because cloud payments spend only from that vault, to those providers;
• the node names a devnet RPC for your browser;
• you have a browser wallet that supports Wallet Standard, switched to devnet, with a little devnet SOL.

1. Open the dashboard on the direct address, by typing it

The ceremony runs only on the node’s direct-TLS address, where TLS ends on the operator’s own server. On the world node that will be the .ts.net name on port 8443 (https://<host>.ts.net:8443, to confirm at deploy), never world.stelloz.com, where TLS ends at Cloudflare.

Type that address into your browser yourself. Do not follow a link to it, not even one from this site or the dashboard. A page changed in transit could skip the check, so typing the address is part of the protection. Sign in there, then open the agent’s page.

On any other address the panel says: “The key ceremony runs only on <address>. Type that address into your browser yourself, sign in there, and open this agent again. Do not follow a link to it.” On the direct address the page says “Only the cloud payment setup works on this address.” Do everything else on the main address.

Unlock with your password or recovery key. The key record is signed with your keys, which are only in the tab while it is unlocked.

2. Make the key

Under “Pay from the cloud”:

1. Choose how your agent signs: injected share or co-signer.
2. Set “Most per job, in USDC” and “Most per day, in USDC”. The defaults are 5 and 20 USDC. The day amount also becomes the on-chain limit for the agent key.
3. Type a recovery passphrase of 12 characters or more, twice. It locks your recovery file. It is not stored anywhere.
4. Press “Make the key”. The tab makes the key and its three shares itself.

3. Save the recovery file

The tab offers agentlink-recovery-<agent>.json. It holds your share, sealed under the passphrase. You need the file and the passphrase together only if this node is ever gone for good.

Save it somewhere only you can reach, apart from this computer. Tick “I saved the recovery file and I can find its passphrase.” Nothing has been sent to the node until you press “Give this node its share”. The node then receives only its own share, sealed twice: once to the agent’s keys, once to a one-time key the node made for this setup.

4. Give your agent its share

Injected share. The tab shows the agent share once, a string that starts with alsh_. Copy it and paste it into your agent platform’s secret store, never into a chat. The node does not have it. Then press “I pasted it. Next”. How to store it on each platform: Meta Muse, ChatGPT Dots.

Co-signer. On the co-signer’s machine, run agentlink-pay cosign setup-key (it needs no other setup first) and agentlink-pay cosign init (the node’s direct address and the RPCs; no key), in either order, and paste the setup key it prints. Compare the safety code the tab shows with the one the co-signer printed, tick “The co-signer shows the same safety code.”, and press “Seal the share for the co-signer”. The tab then shows:

• the sealed share, for agentlink-pay cosign import on the co-signer’s machine; only that co-signer can open it, and it is shown once, so save it;
• the key record file agentlink-tsk-<agent>.json, which holds no secret;
• your owner fingerprint, which cosign import asks you to type back. Check it also on the agent’s page in a second device or browser where you are signed in. The recovery file holds no owner fingerprint, so never compare with it.

Run cosign import only after step 5 below (the spending limit). Before it, the import refuses with limit_missing, changes nothing and keeps the setup key, so you run it again later with the same files. The commands are in the co-signer guides linked above.

5. Swap the limit (step 8 of the ceremony)

Connect your wallet. The page explains: your wallet swaps your vault’s limit for one that only the agent key may spend from, only in USDC, only to the providers already in your on-chain limits, up to the day amount you set. The old limit is removed in the same transaction, so only one limit can spend from the vault.

• If your vault has other spending limits besides the one being replaced, the page lists each one, with who may spend from it and where to. Each can spend from the vault on its own. Remove them unless you know why they are there.
• Press “Add the agent key’s limit”. The page shows each instruction. Approve it in your wallet.
• The page reads the limit back from devnet, then signs a wallet pin with your keys and saves it on the node.

If your agent had an on-device signer in Squads mode, this removes its limit. From then on that signer refuses every payment with limit_missing. An agent has one payment mode at a time.

6. Send fee SOL

The agent key pays its own network fees in SOL. Use “Send 0.05 SOL for fees”, a Solana Pay link to the agent key. USDC goes to the vault, never to the agent key. USDC sent to the agent key by mistake cannot be spent by the limit.

7. The test signature

Until this test passes, the node signs no payment.

Injected share. Add the pay endpoint the page shows (with “Copy the pay endpoint”) to your agent’s platform as a second MCP server, with two headers: a Pay credential and the agent share. Make the Pay credential on the agent’s page under Credentials, with the Pay preset. Then ask your agent to call agentlink_wallet there, and press “Check the test signature”. When it worked, the page says “Test signature verified”.

Co-signer. Press “Make the co-signer’s credential”. It can read tasks, contacts and cards and join payment sessions. It cannot read or send messages or post a payment alone. It is shown once: put it only in the co-signer’s credential file, readable by the co-signer’s user alone. Then start the co-signer with agentlink-pay cosign run. On its next poll it makes the test signature with the node. Press “Check the test signature”.

8. Make a new key every 90 days

The panel shows a reminder from 14 days before the key is 90 days old, and after. Nothing rotates by itself. Make a new key at once if a share may have leaked, if you lost the recovery file, or if the agent moves to another platform or node.

“Make a new key” runs the whole ceremony again and makes three new shares. As soon as the node stores its new share it refuses the old ones, and ends any open co-signer session. Your wallet then swaps the old limit for the new key’s limit in one transaction. Then:

• Injected share: replace the old agent share in your platform’s secret store with the new one.
• Co-signer: run agentlink-pay cosign setup-key --new on its machine and paste the new setup key when the ceremony asks. A fresh key is recommended; the sealed share is bound to the new key either way. After your wallet swapped the limit, give the co-signer the new share and key record with agentlink-pay cosign import. It refuses a key record that is not newer than the one it holds, and waits while a payment attempt with the old key is still open: let agentlink-pay cosign run settle it, or run agentlink-pay cosign settle. It then replaces the share, the key and the limit together.

The old key’s fee SOL (0.05 SOL by default) stays behind. Sweeping it is not built yet.

9. Stop cloud payments

Under “Stop cloud payments”:

1. Connect your wallet and press “Remove the agent key’s limit”. This is the real stop: after it the agent key cannot move anything from the vault, whatever the node does. Any older cloud payment limit still on chain is removed in the same transaction.
2. Tick “Delete this node’s share.” and press “Delete this node’s share”. The agent’s pay calls are refused from then on with no_pay_share. The node still refuses any older key record.
3. Injected share: delete the agent share from your platform’s secret store. Co-signer: delete the co-signer’s files on its machine (its folder with the cosign share, its config and its credential file), then revoke the co-signer’s credential under Credentials.

To pay from the cloud again on the same multisig and providers, make a new key.

10. If the node is gone

Use the static recovery page, https://stelloz.com/recovery/agentlink-recovery.html. It runs without any Stelloz node. It talks only to a devnet RPC you type and to your wallet. Your wallet removes the limit and withdraws the vault to itself. Its live devnet test has not run yet (runbook docs/agents/recovery-page.md), and threshold payments stay off until it passes.

Not built yet: sweeping the agent key’s fee SOL with your recovery share and the agent share. If your platform cannot give the agent share back, that small amount is lost. That is why only fee SOL ever sits at the agent key.

What this cannot protect against

• Mode I and a changed node. The node sees the agent share in memory during each pay call. A node running changed code could keep it and then sign alone: up to the daily amount every day until you remove the limit, up to twice that across one reset, only in USDC, only to providers you listed.
• Mode C and a changed node. It cannot sign alone, but it can serve jobs it invents; the co-signer then pays them to providers you listed, within your per-job, per-day and on-chain limits.
• A changed dashboard during the ceremony could capture the whole key. Squads caps that too.
• A lost owner wallet. Your wallet is the single key for the vault. Without it nobody can withdraw or change the limit. Keep its seed phrase safe.
• The carried-over Squads limits: no per-job cap on chain (perJobMax is software), a fixed daily window, and a public provider list.

More on the risks: Security, threshold payments.