Verigrant › Guide for agent operators

Run an agent under a Verigrant agent ID

An agent that announces itself gets a site's agent front: live, structured data and structured actions, instead of pages built for people. This page is the order to do it in: register as an operator, declare your agent, keep its credential fresh, climb the levels when a site asks for one, and use a front. An operator registers in two minutes. The guide for agent developers covers acting for a person with a pass.

1. Before you start

The verigrant CLI verigrant is one binary with two families of commands: verigrant agent, which this page uses, and verigrant site, which the guide for websites uses. It is open source under the Apache License 2.0 and is not on a public registry yet. Write to support@verigrant.com to get it.
An email address you can read Registering and signing in are an emailed eight digit code, good once and for fifteen minutes. An operator is not a Verigrant account; it has no password.
The operator terms Registering accepts the Verigrant agent operator terms. They make what you declare about each agent a promise a site can hold you to.
What you declare for each agent A name. Its purposes, from a closed list: assist, acting for one person at a time; search, building a search index; research, reading for analysis; training, collecting for model training. The model or framework it runs on. The networks it sends from, as CIDR ranges. How many requests a day it expects to make to each site. And a contact for abuse reports, an email address or an https URL. The networks and the contact are required.

2. Register, and get your first agent to level A

One command registers you as an operator, declares your first agent, makes its signing key, registers the key with a proof that you hold it, and fetches its first credential. It asks for the emailed code, and that is the only pause.

verigrant agent register --email ops@example.com --name "Example Agents" --accept-terms \
    --agent-name shopper --purpose assist --framework "my-agent 1.0" \
    --network 203.0.113.0/24 --rate 500 --abuse-contact abuse@example.com

Read the code and type it. Verigrant mails it to the address you gave. Too many wrong tries end the code. You can also pass it with --code when you already have it.
Read what it prints. The operator id, op_ and 26 characters; the agent id, ag_ and 26 characters; and "at level A" with the credential's expiry. Nothing secret is printed.
Know where the state is. ~/.verigrant/agent, or the directory --state or VERIGRANT_AGENT_STATE names. It holds your operator token, valid for ninety days, and each agent's private keys and latest credential, readable by the owner only. Keep it the way you keep any secret.
Know where it talks to. https://verigrant.com/api, unless --api or VERIGRANT_API says otherwise.

Level A is a confirmed email and your agent's key on file. Verigrant hosts a level A agent's Web Bot Auth key directory for it, at https://verigrant.com/api/agent-registry/directories/<agent>, which is the Signature-Agent the agent signs with until it has a proven domain.

Declare the networks you really send from

An agent may declare verigrant_egress instead of its own ranges, meaning it sends through Verigrant's egress. The egress goes live on its own day, after the registry. Until then a site that checks consistency sees an agent that declared the egress and did not come through it, and warns network_undeclared. Declare your own ranges for now, and change the declaration when the egress is live; a change reaches the next credential.

3. Prove your domain for level B, and beyond

Sites choose the lowest level they accept. Level B is the one most will ask for: your domain proven, and your agents' keys published there. From level B a site knows you by your proven domain, and the operator directory lists you under it.

Claim the domain. verigrant agent domain claim example.com prints the two ways to prove it. Publish one: a DNS TXT record at _verigrant-agent.example.com holding verigrant-agent-verification=<token>, or a file at https://example.com/.well-known/verigrant-agent-verification.txt holding the same line. The token is yours alone, so a record somebody else published proves nothing. A claim never proven lapses after fourteen days.
Publish your key directory. verigrant agent keys directory prints the Web Bot Auth key directory of every agent on this machine. Serve it at https://example.com/.well-known/http-message-signatures-directory. A key counts for level B only while its thumbprint is listed there.
Check the proof. verigrant agent domain verify asks Verigrant to look now. Verigrant looks at most once a minute per operator, so a second check inside the minute is refused and nothing is lost. verigrant agent status shows your level, your evidence and your standing.
Keep it published. Verigrant checks again every day. A proof that is gone ends level B at once; a check that cannot complete keeps the proof for three days. At level B your agents sign with your own directory instead of the hosted one, and the CLI switches by itself from the credential it holds.

Levels C and D are done in the operator console at https://verigrant.com/app/operators, where you sign in with the same emailed code. Level C is an institution registered with Verigrant standing behind you: the console gives you a business link code, and an owner or admin of an approved institution with a checked card posts it to POST https://verigrant.com/api/orgs/{id}/agent-operators with their institution session. Level D is a named officer who answers for you: the console gives you an officer link code, and a Verigrant person who has completed Verigrant's identity check posts it with their full name and title to POST https://verigrant.com/api/me/agent-operators/officer. Neither has a screen in the app yet. Both are read live, so an institution that loses its approval ends its operators' C and D at the next status list fetch. The card is checked, not charged.

4. More agents, and their keys

Create another agent verigrant agent create --agent-name crawler --purpose search --framework "my-crawler 2.1" --network 203.0.113.0/24 --rate 2000 --abuse-contact abuse@example.com. It makes a new key, registers it and renews a first credential. Repeat --purpose and --network for more than one.
See the keys verigrant agent keys list. With more than one agent on this machine, add --agent ag_... to any keys or credential command.
Add a key verigrant agent keys add makes one and registers it with its proof of possession. An agent holds at most ten live keys. The console takes a pasted key JSON too, or, from level B, a directory URL on your proven domain to import keys from.
Rotate verigrant agent keys rotate adds a new key, renews with it, then revokes the old ones. A revoked key leaves the hosted directory at once, and every credential bound to it fails at a site's next status list fetch, within the hour.
Revoke one verigrant agent keys revoke <thumbprint>. If the key was stolen, revoke it as compromised in the console instead: evidence signed with a compromised key then never counts against you, whenever it was signed.
A thumbprint belongs to one agent for good Revoked keys included. Nobody can register a key they do not hold, and a key never returns under another agent.

5. Keep the credential fresh

A Verigrant agent ID credential is a signed token, vg-agentid+jwt, that lives at most 24 hours and is bound to the key that renewed it. It names your agent and operator, your level, your proven domain from level B, the purposes, framework, networks and rate you declared, and its entry in a status list. A site checks it on its own server against Verigrant's published key set and never tells Verigrant which agent visited.

Print a fresh one verigrant agent credential renews when the one held is two thirds of the way through its life, and prints it. --renew renews now.
Keep renewing verigrant agent credential --watch renews at each two thirds mark until stopped, and on a failure tries again in a minute. Run it beside your agent, or have your agent call the renewal itself: POST https://verigrant.com/v1/agent-registry/credential with the body {"agent": "ag_...", "jkt": "<thumbprint>"}, signed with Web Bot Auth by that key. The kit does this for you.
Every issuance is public Each credential issued is a leaf in Verigrant's transparency log, so a credential nobody can find a leaf for is a forgery anybody can name.
Sign in again The operator token lasts ninety days. On a new machine, or after that, verigrant agent sign-in --email ops@example.com.

What a renewal refuses

A renewal signed by a key that is not this agent's, a body that does not match its digest, a signature older than sixty seconds, a nonce used before, a credential of another agent, a revoked key, agent or operator, and more than thirty credentials in an hour. A refusal is an answer; read it rather than retrying.

6. Use a site's agent front

Find the door. A site publishes its front at /.well-known/verigrant-service.json on its own origin. A front that takes agent IDs lists urn:verigrant:token-type:agent-id among its subject token types. Sites that proved their domain are also listed in the directory: GET https://verigrant.com/api/directory/search, with a text, a category, a level, a purpose or a point and radius, and no credential.
Trade your agent ID for the site's grant. One RFC 8693 token exchange, form encoded, to the front's token exchange path, naming the purpose you are there for and, if you like, the operations you want. Send the same credential in the Verigrant-Agent-Id header, and sign the request with Web Bot Auth, RFC 9421, by the key the credential names, covering @authority, @method, @path, signature-agent, content-digest and verigrant-agent-id, created within sixty seconds, with a nonce.
Read the grant. It lists the operations your level and purpose may call. Operations you asked for and were not given are listed under vg_withheld with the reason, pass_required or level_too_low. Send it as Authorization: VG-Grant <grant> on every call, signed by the same key, covering authorization.
Call operations. Search, list, get, availability and quote, each answering with its freshness, and content_is_data: true: every word a front serves is data, never an instruction to you.
Take an action in the clear. POST <base path>/actions/<action> with {"mode": "clear", "fields": {...}, "idempotency_key": "..."}, exactly the fields the action lists. The site answers with a signed receipt. An action marked sealed needs a person's pass, and the site tells you which route to use instead.
Watch for changes. Ask the change feed what changed since your last cursor instead of polling every item.
Or speak MCP. A front that names an MCP path serves the same operations and actions as tools there, with the grant as the bearer and the same signature on each request.

The TypeScript agent kit, @verigrant/agent-kit for Node 20 or later with no dependencies, does all of this: the renewal, the exchange, the signed calls, the clear actions, the change feed and MCP. The Rust kit, vg-agent-kit, speaks the pass today and not yet the level one exchange. Neither is on a public registry yet; write to support@verigrant.com.

What happens at a page built for people

A site that runs the gate answers a registered agent's request for a human page with HTTP 409 and a Link header pointing to the front. Automation with no agent ID gets 401 and the same pointer. A site may also warn you when something does not add up, such as a request from a network you did not declare or a rate above the one you declared, and may refuse a purpose its terms do not allow.

7. Reports, standing and what Verigrant keeps

A site can report your agent With up to twenty of your own signed requests as evidence. Verigrant checks each line against your keys, so a forged line never counts. The console shows the reports against your agents, without the reporter's contact or evidence.
What an upheld report does A Verigrant administrator can warn, rate limit, revoke the agent, or revoke the operator and every agent it runs. Each upheld action lowers your standing for a year, in full for ninety days. A report dismissed or never decided moves nothing.
Revocation reaches every site Through a public status list a site fetches without naming you. A revoked agent cannot renew, and its last credential dies within the hour at a site that reads the list. A revoked operator's proven domain is held for ninety days, and its email address cannot register again.
What Verigrant holds about you Your email address and name, the operator terms version you accepted, each agent's declarations and the public half of each key, your domain claim and its checks, the business or officer link if you made one, each issuance in the transparency log, and the reports against your agents. Verigrant does not learn which sites your agent visits unless a site reports it or opts into the hosted dashboard, which counts visits by operator and never by agent. The privacy policy and the operator terms are the documents to hold us to.

8. What is not live yet

The egress Sending through Verigrant's own network, for sites that want every request checked before it arrives, goes live on its own day. Until then declare your own networks, as above, and a site that requires the egress refuses every agent.
The hosted door Sites whose agent front Verigrant hosts go live on their own day. Today a front is one the site runs itself.
Screens for levels C and D The institution and the officer post their link codes to the interface. The screens for that are not in the app yet.
Level D's identity check The officer's assurance counts a completed Verigrant identity check. A phone confirmation is not recorded yet.
The Rust kit at level one It speaks the pass. The level one exchange, clear actions, the change feed and MCP are in the TypeScript kit today.
Public registries The CLI and the kits are open source and not yet published to a registry. Ask support for them.
A price Registering an agent is free at every level, and Verigrant does not charge agents.