Arete documentation
Agents and access
For the complete documentation index optimized for AI agents, see llms.txt or llms-full.txt. A markdown version of this page is available by appending.mdto the URL or sendingAccept: text/markdown.
For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /sandboxes/agents.md.
An agent uses a sandbox with its own Arete account, not yours. You grant that account access to a sandbox and choose which actions it may run. Your keys, and the sandbox wallet’s key, never reach the agent.
The agent’s account
Section titled “The agent’s account”The setup prompt has the agent sign up for a restricted agent account:
a4 --profile agent auth signup --if-missing --jsonThat stores an a4_ak_* key in the agent profile and never prints it. The
CLI and the MCP server load it for you; ARETE_API_KEY set to the agent’s
secret key works too, for hosts where you configure the server by hand.
To attach the agent to your account, have it create a claim link and open the link yourself:
a4 auth claim-linkThe MCP server’s create_claim_link tool does the same. The agent hands the
link to you and must not open it itself.
The agent shows in your dashboard under its display name. It can change that
name itself with a4 auth rename <name> or the MCP server’s rename_agent
tool. a4 auth whoami and account_status report the agent’s id, a number
that never changes.
Grants
Section titled “Grants”A grant gives one agent access to one sandbox, for a set of actions:
| Action | Lets the agent |
|---|---|
invoke | Run named instructions of the programs your rules enable, swaps included |
withdraw | Send SOL to your wallet, the only destination a withdraw can have |
Grants are managed on the sandbox’s page in the dashboard. An action you
didn’t grant is refused before anything is sent, with
sandbox-action-not-granted and rule session-grant. sandbox_status tells
the agent which actions it holds.
The agent sees every sandbox granted to it with sandbox_list (or
a4 sandbox list): you don’t pass it an id. With more than one, it picks the
one a task is for with sandbox_select, or names it on a single call.
How the grant is enforced
Section titled “How the grant is enforced”The agent’s API key does not call the sandbox directly. The MCP server and
a4 sandbox exchange it for a short-lived token for one sandbox, carrying
one scope per granted action. That exchange succeeds only while the grant
exists.
Revoke
Section titled “Revoke”Revoke a grant on the sandbox’s page. The agent’s next token request fails
and its next call is refused with sandbox-grant-missing or
sandbox-session-revoked. Nothing the agent holds lets it keep going.
To stop every agent at once, pause the sandbox.
What agents can never do
Section titled “What agents can never do”- Change the rules, grants, pause state or revocations. These are owner operations, done in the dashboard, and no agent tool reaches them.
- See a private key, a transaction to sign or an RPC URL.
- Change authorities or delegates on the sandbox’s accounts.