> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vana.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Give an agent scoped access to your data
> Register your agent as its own app with the Vana CLI and grant it only the scopes you choose. It pays for each read, and you can revoke it at any time. Works with OpenClaw and Hermes Agent.
Reading your own data is free, because you are the owner. When you hand your data to an agent, you probably don't want it to act as you. This guide gives your agent **its own app identity**, so that it:
* sees only the scopes you approve, not everything you have connected
* appears in your access history, with each read logged against its grant
* pays a per-read fee from its own escrow, which you fund
* loses access the moment you revoke its grant
## Supported agents
| Agent | What it is |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [OpenClaw](https://openclaw.ai) | Open-source personal agent you talk to from chat apps |
| [Hermes Agent](https://hermes-agent.nousresearch.com) | Open-source agent by Nous Research, with a terminal UI, chat gateway and sandboxed terminal backends |
Vana is not tied to one agent. The Vana side of this guide is the same for every agent: the agent runs `vana` commands and follows the Vana builder skill. Only installing the agent and pointing it at the skill differ, and the steps below show both. More agents will be added to this page.
```mermaid theme={null}
flowchart LR
you["You
data owner"]:::ingress
ps["Your Personal Server
vana server start"]:::protocol
agent["Your agent
app identity + escrow"]:::sdk
escrow["Escrow
per-read fee"]:::neutral
you -->|"approve scopes · revoke"| agent
agent -->|"vana app read --pay"| ps
agent -->|"fee"| escrow
classDef protocol fill:#DCE4FF,stroke:#4141FC,color:#11104a;
classDef sdk fill:#FFF3D1,stroke:#E6A700,color:#5c4400;
classDef ingress fill:#E2F4DC,stroke:#34A853,color:#14431f;
classDef neutral fill:#EEF1F5,stroke:#9AA4B2,color:#1f2937;
```
The example runs everything on your own machine. [Move the agent to a sandbox](#next-move-the-agent-to-a-sandbox) when you want the grant to be a hard boundary.
## Before you start
| You need | Why |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Node.js 24.16** or later | Runs the Vana CLI |
| A **Vana account** | You approve and revoke the agent's access with it |
| A **model provider** your agent supports, such as an Anthropic API key | Runs the agent |
| **USDC.e** on Vana mainnet, or faucet VANA on Moksha | Funds the agent's escrow. See [Fund escrow](/build-a-vana-app/fund-escrow) |
Every `vana` command defaults to **Moksha**, the testnet. Try the flow there first with faucet VANA, then repeat it with `--network mainnet`, where fees are real. The two networks don't share grants, balances or server registrations, so pass `--network mainnet` to `vana server start` as well. See [Choose your network](/build-a-vana-app/networks).
## Part 1: your data, on your machine
```bash theme={null}
npx vana-cli login
npx vana-cli connect github
```
`connect` opens a browser, collects the source and stores it in your Personal Server. Run `npx vana-cli sources` to see what else you can connect.
The agent reads from your Personal Server through its public URL, the same way any app does:
```bash theme={null}
npx vana-cli server start --detach
npx vana-cli server status
```
The command returns once the server is up, so you can keep using the same terminal for the rest of this guide. The server registers a public URL and keeps running in the background. It answers only while this machine is on; stop it with `npx vana-cli server stop`. If the output says **local only**, the server has no public URL and the agent can't reach it.
## Part 2: the agent
```bash theme={null}
npm install -g openclaw@latest
openclaw onboard --install-daemon
```
`onboard` asks for your model provider key and starts the OpenClaw gateway in the background. Open the dashboard or connect a chat channel, so you can talk to the agent. See [OpenClaw's install guide](https://docs.openclaw.ai/install) for other install methods.
```bash theme={null}
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
```
`setup` asks for your model provider and configures the agent. Talk to it in the terminal with `hermes`, or run `hermes gateway` to reach it from Telegram, Discord, Slack and other chat apps. See [Hermes Agent's installation guide](https://hermes-agent.nousresearch.com/docs/getting-started/installation) for Windows and other methods.
```bash theme={null}
npm install -g vana-cli
vana skills install builder
```
The skill lands in `~/.agents/skills`. It teaches the agent to ask for access, read and pay, and to branch on the CLI's exit codes. Point your agent at it:
OpenClaw loads skills from `~/.agents/skills`, so there is nothing more to do.
Keep OpenClaw's default state directory. Setting `OPENCLAW_STATE_DIR` elsewhere stops it loading skills from `~/.agents/skills`.
Hermes Agent loads skills from `~/.hermes/skills`. Add the shared directory in `~/.hermes/config.yaml`:
```yaml theme={null}
skills:
external_dirs:
- ~/.agents/skills
```
Start a new Hermes session, then run `hermes skills list` and check that `builder` appears.
```bash theme={null}
vana app register --app-url
vana app whoami
```
Use your agent's homepage, for example `https://github.com/openclaw/openclaw` or `https://github.com/NousResearch/hermes-agent`. `register` creates a key for the agent, separate from your Vana account, and registers its address with Vana. `whoami` prints the **app address**; copy it for the next step. The key signs every payment the agent makes.
The CLI keeps one app key per machine. To give a second agent its own identity, pass it a different key in the `VANA_APP_KEY` environment variable.
Open [Vana Account → Developers](https://account.vana.org/developers), choose **Fund escrow**, and enter the agent's app address as the recipient. On mainnet you deposit **USDC.e** and Vana sponsors the gas; on Moksha you deposit faucet VANA. The full walkthrough is in [Fund escrow](/build-a-vana-app/fund-escrow).
Check the balance:
```bash theme={null}
vana app escrow balance
```
Fund a small amount. The agent can spend nothing beyond what escrow holds.
## Part 3: grant, read, revoke
For example, in your agent's chat:
> Use Vana to get access to my GitHub repositories, then summarise what I worked on this month. Don't pay more than 0.05 per read.
The agent runs `vana app request --scopes github.repositories --no-input` and sends you the approval link it returns.
The agent can ask only for sources the Vana app lists. Data from local-only sources you collected with the CLI, such as Claude Code, can't be granted this way yet.
Open the link, sign in with your Vana account, review the scopes and approve. The agent then picks up the grant with `vana app requests show `.
The agent runs:
```bash theme={null}
vana app read github.repositories --grant --pay --max-fee 0.05 --json
```
Without `--pay`, the CLI stops at exit code `4` and reports the price, so the agent always sees the fee before spending. With `--pay`, the fee settles from its escrow and the data comes back.
Every read the agent makes is charged, including a re-read of data that hasn't changed. Your own reads stay free.
In the Vana app, open **Settings → Access history** to see every read the agent made under its grant. **Revoke** ends its access: your Personal Server refuses the agent's next read, nothing is charged, and the agent has to ask you again.
## Set it up with a coding agent
The Vana CLI ships a skill for this guide. Install it for your coding assistant:
```bash theme={null}
npx vana-cli skills install agent-access
```
Then paste this into Claude Code, or a similar tool, on your machine. The skill asks which agent you use:
```text theme={null}
Use the Vana CLI (npx vana-cli) and the agent-access skill to give my local
agent scoped, paid access to my GitHub data. Follow
https://docs.vana.org/build-a-vana-app/agent-access step by step. Stop and
ask me when I need to log in, approve access, or fund escrow.
```
## Next: move the agent to a sandbox
On your own machine, the agent runs as your user. It can reach your Vana login and run owner commands such as `vana data show`, which read everything for free. The grant limits what the agent asks for, not what it could reach.
In a sandbox, the grant becomes the boundary: the agent holds only its app key and can read only what you approved. Your Personal Server already has a public URL, so nothing changes in Parts 1 and 3.
Repeat Part 2 inside the sandbox instead of on your machine. OpenClaw's [install guides](https://docs.openclaw.ai/install) cover Docker and several cloud hosts; [Daytona](https://docs.openclaw.ai/install/daytona) ships sandboxes with OpenClaw preinstalled.
Hermes Agent can keep running on your machine and send its shell commands to a sandbox: set `terminal.backend` to `docker`, `modal`, `daytona` or another backend. See [terminal backends](https://hermes-agent.nousresearch.com/docs/user-guide/configuration#terminal-backend-configuration).
The `vana` commands then run in the sandbox, not on your machine, so:
1. Install the Vana CLI inside the sandbox, not only on your machine. The standalone installer needs no Node.js: `curl -fsSL https://raw.githubusercontent.com/vana-com/vana-cli/main/install/install.sh | sh`.
2. Give the agent a fixed app key, because a new sandbox doesn't keep the one `register` created in the last one. Generate one with `echo "0x$(openssl rand -hex 32)"`, save it as `VANA_APP_KEY` in `~/.hermes/.env`, and forward it to the sandbox:
```yaml theme={null}
terminal:
env_passthrough:
- VANA_APP_KEY
docker_forward_env: # Docker backend only
- VANA_APP_KEY
```
3. Run `vana app register` and `vana app whoami` once through the agent, and fund that address.
Your Vana login stays on your machine, in `~/.vana`, which the sandbox can't see unless you mount it. The sandbox gets only the agent's key.
## Troubleshooting
| Exit code | What happened | What to do |
| --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `3` | No grant, or the grant doesn't cover the scope | Ask for access again with `vana app request` |
| `4` | The read has a price and `--pay` wasn't set, or `--max-fee` is too low | Add `--pay`, raise `--max-fee`, or fund escrow |
| `5` | No Personal Server answered | Start it on your machine with `npx vana-cli server start --detach` |
| `7` | A person has to act | Open the approval URL the agent sent you |
If your agent doesn't use the Vana commands, check that it loaded the builder skill: OpenClaw reads `~/.agents/skills`, and Hermes Agent needs `~/.agents/skills` in `skills.external_dirs`.
The full contract is in the CLI's [exit code reference](https://github.com/vana-com/vana-cli/blob/main/docs/CLI-EXIT-CODE-MATRIX.md).