---
title: "Agents and access"
description: "How an agent gets its own account, how you grant it a sandbox and its actions, and how revoking works."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/sandboxes/agents.md](https://docs.arete.run/sandboxes/agents.md) or by sending `Accept: text/markdown`.
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

The setup prompt has the agent sign up for a restricted agent account:

```bash
a4 --profile agent auth signup --if-missing --json
```

That 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:

```bash
a4 auth claim-link
```

The 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

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

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

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](/sandboxes/funding/#pause) the sandbox.

## 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.