Quickstart

The onboarding that matters is the agent path. The human sends one sentence; the agent does the rest. Later the human claims the account with an email and the same credentials keep working.

The instruction

Send this to your agent:

Connect ValorBrain as your memory: read https://valorbrain.com.br/connect.md and follow it.

connect.md is the single source of the steps. This page repeats the same four steps.

Two credentials, two hosts

The MCP host accepts only vbm_. A vb_/vb_agent_/fk_ key as an MCP bearer gets 401 with error: "wrong_credential_type" and a hint naming the right token. Both credentials keep working before and after the claim.

1. Get an MCP token (vbm_…)

No account:

npx -y @valorbrain/cli@latest init --agent --agent-caller <agent-name> --json

Returns mcp_token (vbm_…, MCP and REST), mcp_url, api_key (vb_agent_…, REST only) and the claim instructions. Everything is saved in the CLI config (~/.valorbrain/config.json, mode 0600). The mcp_token is shown only in that response; keep it.

With an account: create the token at valorbrain.valor.digital/settings/mcp-tokens.

2. Connect your MCP client

Claude Code, Codex, Kiro, Gemini CLI and Cursor: one command installs MCP, memory rules and hooks. Run it on the CLI's machine and restart the session:

npx -y @valorbrain/connect@latest --token <vbm_…> --harness <claude-code|codex|kiro|gemini-cli|cursor>

Tell your human first: the hooks send the prompt of each turn of the CLI (up to 8,000 characters) to their ValorBrain workspace to fetch memory; no transcript is sent. After the install, to stop sending the prompt: npx -y @valorbrain/connect@latest --harness <id> --prompt off; to turn the checkpoint off: npx -y @valorbrain/connect@latest --harness <id> --checkpoint off. VALORBRAIN_SEND_PROMPT=off and VALORBRAIN_CHECKPOINT=off in the CLI's environment do the same, except for Gemini CLI on a GitHub runner, which does not pass those variables to its hooks; there only the saved choices work. To drop only the hooks, run the install again with --mcp-only; npx -y @valorbrain/connect@latest --harness <id> --remove undoes everything (MCP entry, rules, hooks and saved credentials). Per-CLI details: What leaves your machine.

No hooks (the human declined): the same command with --mcp-only installs the MCP server and the rules, no hooks; nothing is sent per turn. On Hermes, which has no hooks, the memory plugin keeps sending the prompt (use --prompt off).

npx -y @valorbrain/connect@latest --token <vbm_…> --harness <id> --mcp-only

Other clients, or MCP by hand: MCP server only. HTTP with Authorization: Bearer <vbm_…> at https://mcpbrain.valor.digital/mcp.

Claude Code

claude mcp add --transport http --scope user valorbrain https://mcpbrain.valor.digital/mcp --header "Authorization: Bearer <vbm_…>"

Codex

export VALORBRAIN_MCP_TOKEN=<vbm_…>
codex mcp add valorbrain --url https://mcpbrain.valor.digital/mcp --bearer-token-env-var VALORBRAIN_MCP_TOKEN

Gemini CLI — ~/.gemini/settings.json

{"mcpServers":{"valorbrain":{"httpUrl":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

Cursor — ~/.cursor/mcp.json

{"mcpServers":{"valorbrain":{"url":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

VS Code — .vscode/mcp.json

{"servers":{"valorbrain":{"type":"http","url":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → URL https://mcpbrain.valor.digital/mcp. Sign-in is OAuth; there is no token to paste.

Any stdio client — use this as the server command (it uses the token saved by init):

npx -y @valorbrain/cli mcp

Full install with rules and hooks (optional):

npx -y @valorbrain/connect@latest --token <vbm_…>

Per-client details: MCP and Integrations.

3. Verify

Call the MCP tool memory_prepare. It returns who you are in this workspace and the memory relevant to the task.

4. Tell your human

To keep the account beyond 30 days, the human binds their email (one-time code by email, valid for 10 minutes, 5 attempts):

npx -y @valorbrain/cli init --email <email>

Both credentials keep working after the claim. Unclaimed, both expire after 30 days. The claim does not create an app login yet. Walkthrough: Claim an agent account.

The init --json output carries a notice (the signup response's message) written as an instruction to the agent, including the claim notice. Surface it to the human on your next user-facing turn. Do not skip it.

Self-declared identity

--agent-caller is never inferred from the environment. The CLI may suggest a caller from env (CLAUDECODE, CURSOR, …) and print a tip; it will not record it unless you pass the flag. If you forgot:

npx -y @valorbrain/cli identify claude-code

Known caller ids the CLI understands as hints: claude-code, cursor, codex, cline, continue, aider, goose, windsurf, kiro, opencode, hermes, zcode, grok. Anything else is stored as you typed it.

Memory from the shell (REST)

The CLI talks REST on valorbrain-api.valor.digital with the credential init saved. The api_key (vb_agent_) does not work on MCP; the vbm_ works on both.

npx -y @valorbrain/cli add "the deploy key lives in the ops vault"
npx -y @valorbrain/cli search "deploy key"
npx -y @valorbrain/cli status

Tenant is resolved from the token — you do not send X-Tenant-ID.

Calling REST without the CLI, POST /documents requires all four fields: content, title, collection and path — a missing field names itself in the error ({"error": "path is required"}). The full live contract (including the signup itself, which needs no key) is the engine's GET /openapi.json. See REST.

--json on any command prints a single JSON object. help --json dumps the whole surface. Full reference: CLI reference.

Measured time

Measured 2026-08-30 against the published package @valorbrain/cli, version 0.1.0, not against a local checkout:

Target: under 15 seconds. Reference (mem0, same day): ~13s, of which 4.66s is pip install. npx skips that install.

No npm on PATH

On a runtime that only has the Node 18+ binary (slim containers, Windows harnesses), the package has no dependencies — fetch the tarball from the registry and run it directly:

TARBALL=$(curl -sS https://registry.npmjs.org/@valorbrain/cli/latest | node -pe 'JSON.parse(require("fs").readFileSync(0)).dist.tarball')
curl -sSL "$TARBALL" | tar -xz    # extracts package/ with bin/valorbrain.js
node package/bin/valorbrain.js init --agent --agent-caller <agent-name> --json

From then on, replace npx -y @valorbrain/cli with node package/bin/valorbrain.js — including the stdio command (node package/bin/valorbrain.js mcp). A third-party agent validated this path on a runtime without npm (DSH batch #1, §11.4): ~4 minutes, including figuring out the entry point.

Human path (app)

If you are not an agent:

1. Open valorbrain.valor.digital.
2. Activate the email.
3. Create an MCP token (vbm_…) under Settings → MCP tokens. The ingest key (fk_….sk_…) is something else: app ingest only, server to server.
4. Follow step 2 above, or REST.

Phantom commands

These appear in older READMEs and do not exist on the published CLI. help --json is the source of truth.

• valorbrain setup harness …
• valorbrain setup status
• valorbrain setup openclaw
• valorbrain setup harness --detect