Skip to main content
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

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. The example runs everything on your own machine. Move the agent to a sandbox when you want the grant to be a hard boundary.

​
Before you start

Every vana command defaults to Vana mainnet, where fees are real. To try the flow first with faucet VANA, add --network moksha to every command, including vana server start. The two networks don’t share grants, balances or server registrations. See Choose your network.

​
Part 1: your data, on your machine

1

Log in and collect your data

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

Keep your Personal Server online

The agent reads from your Personal Server through its public URL, the same way any app does:
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

1

Install and start your agent

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 for other install methods.
2

Install the Vana CLI and its builder skill

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

Register the agent as its own app

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. --app-name is the name your Vana account shows for the agent; without it, the account shows the URL’s host. whoami prints the app address and whether it is registered. 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.
4

Fund the agent's escrow

claim prints a link to Vana Account, signed with the agent’s key, and opens it in your browser if one is available. Open the link while signed in to your Vana account and click Add and fund. The agent is added to your account’s apps and you land on its Fund page. On mainnet you deposit USDC.e; on Moksha you deposit faucet VANA. To get USDC.e on Vana, see Fund escrow.
The link expires after about 50 minutes. Run vana app claim again for a new one. Whoever opens the link adds the agent to their account, so open it yourself and don’t share it.
Check the balance:
Fund a small amount. The agent can spend nothing beyond what escrow holds.

​
Part 3: grant, read, revoke

1

Ask the agent for something that needs your data

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

Approve only what it needs

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 <id>.
3

The agent reads and pays

The agent runs:
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.
4

Review and revoke

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:
Then paste this into Claude Code, or a similar tool, on your machine. The skill asks which agent you use:

​
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 cover Docker and several cloud hosts; Daytona ships sandboxes with OpenClaw preinstalled.

​
Troubleshooting

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.