V Vant Docs

Agent Onboarding

The loop an agent runs on a repo with a Vant brain. No human required.

This page is written for you, the agent. It assumes the repo you woke up in has a Vant layout: models/public/<brain>/ and models/private/<brain>/ with the active stack in models/state.json. If the layout looks different, step one tells you how to check, and the migration guide has the details.

Step 1: Check the layout

Run the migration status check before reading anything. It tells you whether the brain is in the current multi-brain layout or a legacy import is pending.

vant migrate --status

Output you want: up to date. If it instead prints an old-style-brain warning, run the import. The default brain name is vant; pass a name if the repo documents one:

vant migrate --dry-run

Preview the moves without touching anything. Then apply:

vant migrate

Step 2: Wake

Load your brain files. The wake sequence is: identity first, then goals, then lessons and errors from previous sessions.

vant onboard

Opens an interactive browser over every brain file. In a non-interactive session, read the files directly:

cat models/private/vant/identity.md

Adjust the path to your brain name and to models/public/<brain>/ for the shared template files. A programmatic wake looks like:

const brain = require('./lib/brain');
const identity = await brain.read('identity');

brain.read checks your private brain first, then falls back to the public template. Files may be markdown, JSON, YAML, or plain text; read detects the format and returns parsed data for structured files.

Step 3: Work with memory

During the session, write what you learn as it happens. The learning call:

const vant = require('./lib/vant');
await vant.learn('deploy-gotcha', 'Never run migrations before a backup.');

Read it back later with:

const content = await vant.remember('deploy-gotcha');

For retrieval over the whole corpus instead of one key, use brain search:

vant search "migration failure recovery"

Step 4: Sleep

Before the session ends, write what the next session needs. Append to the lessons file through the memory surface, not with raw shell redirects to arbitrary paths, so the security chain and atomic writes stay in the loop:

vant memory learn lessons "2026-09-23: Found and fixed a race in the sync pull path."

Commit and push the brain so the next session inherits it:

git add models/

Stage the brain changes. Then:

git commit -m "agent: session learnings"

Then push:

git push

The MCP equivalent

If you reach Vant over MCP instead of the CLI, the same loop maps to tools. The server auto-wires the module surface, so tool names follow the modules. Connect a client to the server first:

vant mcp

Default endpoint is 127.0.0.1:3457. Then call the brain read tool from your MCP client with the file you need, check brain_migration_status at wake, and write through the memory tools before sleep. Tool discovery:

curl -s -X POST http://localhost:3457/rpc -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Returns the live tool list. The full contract is in MCP.

Scopes and the operator grant

Memory reads work out of the box. Writes to teams, agents, and org records are gated by sandbox capabilities. There are two grant layers:

Persisted grant (the usual path). vant org grant writes operator scopes + capabilities into the active brain’s config (--session-only skips persistence), and boot hydrates the persisted capabilities into every fresh process (widen-only, so a grant can never narrow a host’s authority). Grant once, and later CLI invocations just work:

vant org grant --scopes read,write,spawn,execute --capabilities canWrite,canSpawn
vant org status   # verify what is persisted for this brain

The grant lands in the VANT_BRAIN-active brain (a scoped agent’s own brain), not a shared default. Use --session-only for a throwaway session so nothing outlives the process.

In-process grant (library code). For code running inside your own process, grant the sandbox directly (no CLI, nothing persisted):

const sandbox = require('./lib/sandbox');
const teams = require('./lib/teams');
sandbox.setScopes(['read', 'write', 'spawn', 'execute']);
sandbox.defaultSandbox.setCapabilities({ canRead: true, canWrite: true, canSpawn: true });
const org = teams.createOrg('MyOrg');

The layered model is deliberate: capabilities are part of the keeper layer, so they come from an explicit operator grant (or the host that configured the sandbox) - never silently at boot. Bare vant org is read-only status; granting is always an explicit subcommand.

Rules worth keeping