agent-access
Give your own agent (OpenClaw or Hermes Agent today, more to come) its own identity, scoped and paid access to your data, and a way to cut it off. Use when: (1) the user says "give my agent access", "let OpenClaw read my data", "connect Hermes to Vana", "set up an agent in a sandbox with Vana", (2) an agent the user runs should see some of their data but not act as them. This skill is the owner's side. The agent itself uses the builder skill. For collecting data, use connect-data.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- agent-access
- description
- Give your own agent (OpenClaw or Hermes Agent today, more to come) its own identity, scoped and paid access to your data, and a way to cut it off. Use when: (1) the user says "give my agent access", "let OpenClaw read my data", "connect Hermes to Vana", "set up an agent in a sandbox with Vana", (2) an agent the user runs should see some of their data but not act as them. This skill is the owner's side. The agent itself uses the builder skill. For collecting data, use connect-data.
03 SKILL.md 正文
Agent Access
Reading your own data is free, because you are the owner. An agent you run should not act as you. This skill sets it up as its own app:
- it sees only the scopes the owner approves
- every read it makes is logged against its grant and paid from its own escrow
- the owner can revoke it, and its next read is refused
Two roles, often on two machines:
| Role | Who | Holds |
|---|---|---|
| Owner | the person whose data it is | their Vana login and Personal Server |
| Agent | the agent the user picks | its own app key and escrow, nothing else |
Never give the agent the owner's login. Do not copy ~/.vana from the
owner's machine to the agent's.
First, ask which agent
Before running anything, ask the user which agent they want to give access to, and wait for the answer. If they already named OpenClaw or Hermes Agent, confirm it instead of asking again.
- OpenClaw (openclaw.ai)
- Hermes Agent by Nous Research (hermes-agent.nousresearch.com)
Tell them that more agents will be supported. Vana is not tied to one
agent: every agent runs the same vana commands and follows the same
builder skill, and only installing the agent and loading the skill differ.
If they name another agent that can run shell commands, the Vana steps
below still apply. Say that this agent is not a documented path yet, then
in step 2 install the Vana CLI and the builder skill as usual and make
the skill visible to the agent: point its skills directory at
~/.agents/skills, or copy ~/.agents/skills/vana-builder into the
directory its docs name. If it can't load SKILL.md skills at all, give
it the contents of vana-builder/SKILL.md as instructions.
In the same message, ask:
- which data the agent should see (for example GitHub or Spotify)
- whether it runs on this machine or in a sandbox (step 3)
- straight to mainnet (the default, real money) or testnet first (
--network moksha)
Stop for the human
These steps need the person. Say what they need to do, then wait:
- logging in (
vana loginopens a browser) - connecting a source (
vana connectcan open a browser to sign in to it) - the first
vana server start, which can ask them to confirm the install and to register the server in a browser - setting up the agent with a model provider key
- funding the agent's escrow (real money on mainnet)
- approving the agent's request (an approval URL)
1. Owner: data and a server the agent can reach
On the owner's machine:
npm install -g vana-cli # or: npx vana-cli <command>
vana login
vana connect github # or any source from `vana sources`
vana server start
vana server status --json
server start registers a public URL and keeps the Personal Server
running in the background. The agent reads through that URL, so it
answers only while the owner's machine is on. If the output says local
only, the tunnel or the registration failed and the agent cannot reach
the server; fix that before going on.
If server start or server status says the running server was started
by an earlier vana and must be restarted, do it:
vana server stop
vana server start
2. Install the agent and load the builder skill
Follow the section for the agent the user picked.
OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon # asks for a model provider key
npm install -g vana-cli
vana skills install builder
OpenClaw loads skills from ~/.agents/skills, where vana skills install
puts them, unless OPENCLAW_STATE_DIR moves its state elsewhere.
Hermes Agent
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup # asks for a model provider
npm install -g vana-cli
vana skills install builder
Hermes Agent loads skills from ~/.hermes/skills, not
~/.agents/skills. Add the shared directory to ~/.hermes/config.yaml,
merging with any skills: section already there:
skills:
external_dirs:
- ~/.agents/skills
Start a new Hermes session, then check that builder appears in
hermes skills list.
3. Choose where the agent runs
- Same machine: quickest to try. The agent runs as the owner's user, so
it could still reach the owner's login and run owner commands such as
vana data show. The grant limits what it asks for, not what it can reach. - Sandbox: the grant becomes the boundary, because the agent holds
only its app key. Use this for anything real. If the sandbox can be
recreated, it loses the key
registermade in the last one, and the escrow funded to it. Give the agent a fixed key instead: generate it withecho "0x$(openssl rand -hex 32)", keep it outside the sandbox, and pass it in asVANA_APP_KEY. Never mount the owner's~/.vanainto the sandbox.-
OpenClaw: repeat step 2 inside a container or cloud VM (docs.openclaw.ai/install).
-
Hermes Agent: keep it on the owner's machine and set
terminal.backendin~/.hermes/config.yamltodocker,modal,daytonaor another sandbox backend, so its shell commands run there. Thevanacommands then run in the sandbox, so install the CLI inside it (the standalone installer needs no Node:curl -fsSL https://raw.githubusercontent.com/vana-com/vana-cli/main/install/install.sh | sh), and again whenever the sandbox is recreated. Save the fixed key asVANA_APP_KEYin~/.hermes/.envand forward it:terminal: backend: docker env_passthrough: - VANA_APP_KEY docker_forward_env: # Docker backend only - VANA_APP_KEY
-
Step 4 runs wherever the agent's shell commands run.
4. Agent: identity
vana app register --app-url <url that identifies the agent>
vana app whoami --json
Use the agent's homepage as the URL, such as
https://github.com/openclaw/openclaw or
https://github.com/NousResearch/hermes-agent.
register uses VANA_APP_KEY when it is set; otherwise it creates an
app key separate from the owner's account, in the OS keychain where there
is one, or in ~/.vana/app-key.json. It is safe to run again. To run
two agents on one machine, give each its own key through VANA_APP_KEY.
whoami prints the app address; the owner needs it to fund escrow.
5. Fund the agent's escrow (human step)
The simplest path for the person: run
vana app claim --json
and send them data.claimUrl. They open it while signed in to Vana
Account, click Add and fund, and land on the agent's Fund page, where
they deposit from a browser wallet: USDC.e on mainnet, faucet VANA on
moksha. The link is valid for about 50 minutes, and the first Account to
open it takes the app, so send it only to the owner. Run claim again for
a fresh link. Without the claim, the agent is in nobody's Apps list and
Account has no Fund page for it.
From the agent's own terminal instead, the agent's key pays the gas, so its wallet needs VANA as well as the fee asset:
vana app escrow fund --amount 1 --json # moksha: native VANA
vana app escrow fund --amount 5 --asset <USDC.e token address> --network mainnet --yes --json
The asset to fund is the one reads are priced in; a read without --pay
names it as asset in its exit-4 payload.
Then check:
vana app escrow balance --json
Fund small amounts. The agent can spend nothing beyond what escrow holds,
and --max-fee caps each read.
6. Grant: the agent asks, the owner approves
Ask for the data the user chose. request does not check scope names: a
wrong one still returns an approval URL, and fails only when the owner
opens it. Get the exact names on the owner's machine, after vana connect has collected the source:
vana data show github --json # data.requestedScopes lists the scopes
Then the agent runs:
vana app request --scopes github.repositories --no-input --json
That exits 7 with approvalUrl. Hand the URL to the owner. They sign
in, review the scopes and approve only what the task needs. The agent then
picks up the grant:
vana app requests show <request-id> --json
<request-id> is data.requestId from the request. requests show
exits 0 either way: until the owner approves, data.status is pending
and data.grantId is null. Once approved, data.grantId is the grant to
read with. If the owner later revokes it, or a newer approval for the same
app replaces its scopes, data.live turns false, data.grant.state says
revoked or replaced, and next is a fresh vana app request.
Keep requests to sources the Vana web app lists. A request that includes a source it doesn't list cannot be approved on the web, and data from local-only sources (such as Claude Code history) can't be granted this way.
7. The agent reads and pays
vana app read github.repositories --grant <grant-id> --pay --max-fee 0.05 --json
Without --pay it stops at exit 4 with the price. Every read is
charged, including a re-read of data that hasn't changed, so an agent that
reads on a schedule spends on every run. The owner's own reads stay free.
8. Review and revoke
In the Vana app, Settings → Access history lists each read the agent made under its grant. Revoke ends its access: the Personal Server refuses the next read and nothing is charged. To give access again, the agent asks again.
Networks
Everything defaults to mainnet, where fees are real USDC.e.
Grants, balances and server registrations do not carry across networks.
To try the whole flow on the testnet first, pass --network moksha on every
command (every vana command accepts it), vana server start included: an
agent reading on moksha cannot find a server registered only on mainnet.
Failure notes
- Exit 5 on a read: the owner's Personal Server did not answer. Check
vana server statuson the owner's machine. A read refused after a revoke can also report exit 5 today; if the owner just revoked, treat it as final and ask again rather than retrying. - Exit 4 with
--payset:--max-feeis below the price, or escrow is empty. The limit is in the fee's own asset (USDC.e on mainnet). - Exit 7 from
request: nobody has approved yet. Do not re-request in a loop; pollrequests showat a human pace. - The agent never runs
vanacommands: it did not load the builder skill. Recheck step 2 for the agent the user picked. delivery: "enclave"withpaid: false: the owner serves this data from a TEE sandbox, which the gateway currently admits at zero price.
04 同仓库更多 Skills
verify-setup-resume
Verify BUI-936 setup/resume identities, funding readiness and overlapping resumes. Use when changing app request, test-credit transport or the request journal. Runs bounded TLA+ checks and offline real-code replays without live funding or paid reads.
verify-server-supervision
Verify the local Personal Server stop and restart boundary. Use when changing the supervisor's backoff, port probing, replacement launch or Stop handling.
verify-paid-read-recovery
Verify interrupted and overlapping CLI paid reads, receipt-file writers and dead-owner recovery. Use when changing src/cli/app/read.ts, src/core/receipts.ts or src/core/receipts-lock.ts. Runs TLA+ models and offline real-code replays without live paid reads.
verify-mainnet-registration
Verify mainnet app registration and Account association recovery. Use for the registration journal, gateway confirmation, retry, or ownership check.
verify-hosted-provisioning
Verify hosted Personal Server resource ownership across create and delete. Use for Connect's server API, provisioning-row updates, or deprovisioning admission.
verify-export-settlement
Verify queued export owner binding and generation settlement. Use for result publication, pending upload receipts, or retry and sync changes.