Arete documentation
Quickstart: your first sandbox
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/quickstart.md.
This walks through one sandbox from start to finish. You need an Arete account, a Solana wallet with a little SOL, and a coding agent that supports MCP (Claude Code, Cursor, Codex and others; see Connect your agent).
1. Set up your agent
Section titled “1. Set up your agent”Open your agent in a project folder and paste:
Read https://docs.arete.run/agent.md and follow it to set up Arete in your environment. Verify the setup, and simply explain what Arete is capable of.
The agent installs the a4 CLI, signs up for its own agent account and
configures the Arete MCP server. The agent’s account is separate from yours:
it gets its own API key and never needs yours.
2. Create and fund the sandbox
Section titled “2. Create and fund the sandbox”On the Sandboxes page of the dashboard, create a sandbox. It gets a wallet address. Send SOL to that address from your own wallet.
The wallet you fund from matters: your wallet is always an allowed destination, so funds can always come back to you.
3. Build and sign the rules
Section titled “3. Build and sign the rules”In the rules builder:
- Turn on the programs the agent may use.
- Optionally narrow each program to certain instructions, and set a spend limit (for example, at most 1 SOL per day through that program).
- Add any other addresses funds may go to. Leave this empty unless you need it.
- Sign once with your wallet.
The builder generates a Rules v3 document. You can also
write one by hand and check it with a4 sandbox rules validate rules.json.
4. Grant your agent
Section titled “4. Grant your agent”Grant your agent’s account access to the sandbox and choose the actions it may
run: invoke (program instructions, swaps included) and withdraw. You can change or
revoke the grant at any time. See Agents and access.
5. Let the agent find the sandbox
Section titled “5. Let the agent find the sandbox”There is no sandbox id to copy into the agent’s configuration. The MCP server asks Arete which sandboxes the agent has been granted. If this is the only one, every tool uses it.
If you have granted the agent more than one, ask it to choose:
List the sandboxes you have been granted with sandbox_list, then select the one called Treasury with sandbox_select.
The choice is saved for the project folder. Restart the agent host if it was
already running before setup, so the sandbox_* tools appear.
6. Let the agent look around
Section titled “6. Let the agent look around”Ask it to read before it acts:
Use the sandbox tools. Show me the sandbox’s balance, the actions you are granted, and which programs and instructions the rules allow.
The agent calls sandbox_status and sandbox_rules. These change nothing.
7. Preview, then run
Section titled “7. Preview, then run”Give it a task within the rules, and ask it to preview first:
Preview the action first with sandbox_preview and tell me what the wallet would lose. If it passes, run it with sandbox_invoke and show me the result.
sandbox_preview builds the transaction and runs every check without signing
anything. It returns pass with what the wallet would lose, or the refusal
with its code, rule and a hint. sandbox_invoke runs the same action
for real; it is the only tool that moves funds.
8. Check the record
Section titled “8. Check the record”Every action is recorded, refusals included:
a4 sandbox list # the sandboxes granted to the agent, and the one in usea4 sandbox historya4 sandbox holdings