VERAX

Verax

The body an agent asks before it acts.

Listed on: npm · Glama · MCP Registry · MCP Market · mcp.so · Docker Hub · Zenodo

[agora]

Verax is an MCP server that sits between an agent and its tools. Every tool call passes a policy gate and leaves a signed decision record before anything runs; every call that ran leaves an effect row that is reconciled against its record afterwards. A refusal is recorded the same way as an approval. A call the policy will not decide alone is held until an operator approves it, at this machine or, with the operator door set up, from another device with a passkey. The ledger stays on the machine the body runs on, and the body opens only when its authorization is configured: there is no default token.

Break it, and we pay. USD 100 for each valid report of a way for the agent's account to get a refused call allowed, run a call with no decision record, or change the service's code, keys or ledger. The budget is USD 500 in total. Terms: SECURITY.md.

By VERAX Teknoloji. Sister projects: Conarium · Tugra · Cedulon. Decision records use the Cedulon record format.

How Verax compares, dated 15 October 2026: of 40 projects that gate, log or approve an agent's tool calls, nine are compared on four questions with a source for every cell, and the page says where Verax falls short: verax-ai.com/compare.html.

See it run

npx @verax-ai/body demo

[verax demo in a terminal: an allowed memory write, a signed refuse, and a payment held until the operator answers y and types the amount]

The recording is the output of one run in a terminal where the approval question was answered y and the amount was typed. That run took about a second; it is played back slowly here so it can be read.

What it prints, without a terminal to answer the approval question:

verax demo
memory.put / memory.get  allowed; two signed records
message.send -> [email protected]  refused egress-blocked (signed)  ref 6c6e4925-b769-4a8b-8fc4-e2443613a5b6
spend 100 minor USD sample-merchant  held  no terminal to ask, so it stays held (run this in a terminal to be asked)
audit.explain of the refuse  finding none  trust-root own-key  chain and signatures read back
records  5effects  3ledger   removed on exit (run with --keep to keep it and check it with verax verify)
Not shown here: data masking arrives with a downstream server such as Conarium; statement reconciliation needs a real statement (verax reconcile).

Node 22.6 or newer, @verax-ai/body 0.2.1 or later. The command records an allowed memory write and read, a signed refuse of a message to a host off the policy list, and a payment held for the operator on this machine (approved when the terminal answers y and then types the amount, 100; up to 0.5.0 the demo did not print that second question).

--keep leaves the temporary ledger on disk. verax verify <dir> reads it back without a body, as in Read the ledger back without us. To keep it and check it:

npx @verax-ai/body demo --keepnpx -y -p @verax-ai/body verax verify <the directory it printed>

The same rules, animated

Four short episodes show the same gate, with characters in place of a terminal. They are sample scenarios: the scenes are drawn in three.js and the voices are generated with ElevenLabs.

Episode 1, "$1,850": a payment is held until a person approves it on a phone, and changing one cent in the record breaks its signature.

https://github.com/user-attachments/assets/772ae1c4-2697-47a0-a228-36f0508b0d93

Episode 2, "No rule, no way through": a call with no rule is refused, the same call under a new name is refused again, and both refusals are signed.

https://github.com/user-attachments/assets/4fb86627-3310-4f10-b1a9-059d8fcffb28

Episode 3, "The red lever": an operator halts the body, every later call is refused and signed, and a call that was already running is not cut off.

https://github.com/user-attachments/assets/8d19eed9-3359-46b3-bd77-f2b1b1c4dd75

Episode 4, "Who approved?": a held spend waits for verax approve on the machine, the agent cannot approve it, and the approver's operator id goes into the record.

https://github.com/user-attachments/assets/0b8aade4-a970-4b63-835e-4837e2a39cc9

Connect your agent

Elevated verax install and verax approve run a copy of this program that only an administrator can change; a copy your account can change is refused. On Windows a passkey through the operator door (verax install --operator-door <origin>) approves without an elevated shell; without the door, an elevated CLI approve is the way. It has to be run from a separate administrator account, not this account elevated, because a same-user elevated shell inherits that user's environment variables and PowerShell profile, which the agent can set. Clear NODE_OPTIONS in that shell (Remove-Item Env:NODE_OPTIONS). Start that other account's PowerShell with -NoProfile (an elevated shell otherwise runs your $PROFILE, which your account can change):

npm install -g --prefix "$env:ProgramFiles\verax-cli" @verax-ai/body& "$env:ProgramFiles\verax-cli\verax.cmd" install

On Linux and macOS, with a root-owned Node (the distribution's /usr/bin/node, or /opt/verax-node/<dir>/bin/node; the installer prints those steps when the Node it was started from can be changed by your account). Do not start an elevated command with env node:

sudo npm install -g --prefix /opt/verax-cli @verax-ai/bodysudo /usr/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js install

The command installs @verax-ai/body from the npm registry into an administrator-owned directory after signature checks, runs that Node, and keeps the ledger under a service account. On Windows the agent token is %ProgramData%\Verax\agent-token\<your SID>\agent.token (Administrators and SYSTEM have full control, your SID can read the file and read-execute the directory). On Linux and macOS a child process running as your uid writes ~/.verax/agent.token from its stdin. It prints the Claude Code line that reads that file. Port 8787 taken? verax install --port 8797. Node must be the all-users installer from nodejs.org on Windows; a Node your account can rewrite is refused. On macOS the remedy extracts the official tarball as root into /opt/verax-node (root:wheel, not group- or other-writable). On Linux the same place, /opt/verax-node (root:root), which SELinux labels usr_t. On SELinux systems install requires Node labelled bin_t or usr_t (distribution Node is; a tarball under /usr/local/lib is not) and prints the one-line fix. The service then runs in unconfined_service_t. The service account and the file permissions are the boundary.

Approve a held call with verax approve, or, when the install named an origin with --operator-door, from another device through the operator door with a passkey enrolled by a pairing code from verax operator enroll. The passkey panel (verax desktop) is not released yet. On Windows run the approve from a separate administrator account, not this account elevated, in a -NoProfile PowerShell after Remove-Item Env:NODE_OPTIONS: & "$env:ProgramFiles\verax-cli\verax.cmd" approve. Linux and macOS, naming the root-owned Node: sudo /usr/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js approve or sudo /opt/verax-node/<dir>/bin/node /opt/verax-cli/lib/node_modules/@verax-ai/body/dist/cli.js approve. Uninstall the same way, with uninstall in place of approve.

To try it in your own user, which is not a boundary:

verax init --local ~/.veraxverax serve --env-file ~/.verax/verax.env

claude mcp add --transport http verax http://127.0.0.1:8787/mcp --header "Authorization: Bearer $(cat ~/.verax/local-issuer/agent.token)"

The token can read and write memory through the gate; it cannot approve. The shipped policy refuses spend until you add a rule for it; a call your policy holds waits for verax approve on this machine, or for an approval through the operator door when one is set up. See docs/THREAT_MODEL.md.

With Conarium

@verax-ai/body 0.2.2 and later accepts --with-conarium. 0.2.1 does not carry the flag. The flag has npx download @conarium-ai/core from npm and run it as a child process; that needs a network.

Conarium masks the rows, and its sample policy denies its public.secrets table. Verax puts each call through the same gate as its own tools, keeps a signed record and a hash of the answer, and refuses a downstream tool the policy does not name before the child sees the call. When Conarium answers with an error, the body tells the caller that it did, not what it said.

What it prints, without a terminal to answer the approval question:

verax demo
memory.put / memory.get  allowed; two signed records
message.send -> [email protected]  refused egress-blocked (signed)  ref 6c6e4925-b769-4a8b-8fc4-e2443613a5b6
spend 100 minor USD sample-merchant  held  no terminal to ask, so it stays held (run this in a terminal to be asked)
conarium.query customers  allowed; masked by Conarium before the rows left it  measured [MASKED_PII] on every email and card
conarium.query public.secrets  allowed by this gate; Conarium answered with an error and no rows  recorded as a failed call
conarium.list_tables  refused no-rule (signed)  refused by this gate; the downstream server never saw the call
audit.explain of the refuse  finding none  trust-root own-key  chain and signatures read back
records  8effects  5ledger   removed on exit (run with --keep to keep it and check it with verax verify)
Not shown here: a real database (these are Conarium's sample rows); statement reconciliation needs a real statement (verax reconcile).

What ships

The three packages are published together and carry the same version; the capability matrix in docs/STATUS.md names the current one, and it is the version on npm. The body is also listed in the MCP registry as io.github.verax-ai/verax. What that version carries, what it does not, and the test holding each row up are in the capability matrix at the top of docs/STATUS.md.

Read the ledger back without us

A ledger only the vendor's running service can read is evidence a buyer rents, not evidence they hold. verax verify reads a state directory on its own — no body listening, nothing on the network — and states each check on its own line, because they fail separately. On a copy of the ledger npx @verax-ai/body demo --keep leaves behind, 0.6.0 prints:

$ verax verify ./verax-stateledger        ./verax-statedecisions     5effects       3 (3 bound to a decision, 0 with none)signatures    5 verify, 0 do notchain         unbrokenverified with the key carried in these files              verified against the key carried in the records themselves: this shows the files are internally consistent, not that the key was ever trusted. Pin a key you hold to check that.effects with the key carried in these files              verified against the key carried in the self effects themselves: this shows the files are internally consistent, not that the key was ever trusted. Pin a key you hold to check that.same-org with no key              no same-org effects, so no witness key was usedcheckpoints with no key              no checkpoints, so no checkpoint key was usedindex: 5 ref(s), each still a decisioneffect completeness checkedinputs: 5 record(s), each with its inputs rowtail: no checkpoint; removing the newest records with their effects is not detectable from these filescontrol: no control recordsanchors: none (no checkpoint is registered with a transparency service)approval signatures  signed-verified 0 | signed-failed 0 | unsigned-http 0 | cli 0              no operator key was found in these filescontrol signatures   signed-verified 0 | signed-failed 0 | unsigned-http 0 | cli 0 | file 0starts        1; largest gap none; previous beat missing at 1792241614080; 1 of 1 signed verify under the in-ledger record key
VERIFIED (internal consistency only)

The demo approves nothing and halts nothing, so both signature counts are zero; an approval given through the operator door is counted on the approval signatures line (remote approval). tail and anchors are about checkpoints, below. starts summarizes the heartbeat (Watch for silence).

The verified with the key carried in these files pair is the point. Checking a ledger against the key lying next to it proves the files agree with each other and nothing more — anything able to write the ledger could write that key too. Pass --key <public.pem> to verify decision records against a copy you hold, and the answer says a key you supplied instead. Effects are signed with a separate key. A self row is checked under the effect key: --effect-key <public.pem> when you pin it, otherwise one key taken from the first self row. A same-org row is checked under the witness key: --witness-key <public.pem> when you pin it, otherwise one key taken from the first same-org row. Pinning --effect-key while a same-org row is present requires --witness-key as well, and pinning --witness-key while a self row is present requires --effect-key as well; otherwise the result is not verified. Each of those lines says the same thing: the files agree with each other, not that the key was ever yours. The last line says it too: VERIFIED (internal consistency only) while any key, operator credentials included, came from the files; VERIFIED (tail not covered: ...) while newest records have no checkpoint over them; VERIFIED (rollback not checked: no anchored checkpoint) without a receipt that verifies under --anchor-key; and VERIFIED with all of those in place. Checkpoints are signed by the witness key. Every checkpoint row is checked under one key: --checkpoint-key <public.pem> when you pin it, otherwise one key taken from the checkpoint file, with the same note that agreement is not trust. The tail counts only checkpoints whose signatures verified. Someone who can rewrite the files can still roll that file back to an older valid prefix together with the records after it; only a checkpoint held elsewhere detects that. --json prints the same result for a pipeline; the exit code is 0 when it verifies and 1 when it does not, and a directory with no ledger in it is never quiet success.

Records are COSE_Sign1 with algorithm -19 (Ed25519, RFC 9864), not the older polymorphic -8 (EdDSA). Some COSE libraries do not know -19 yet: as of go-cose 1.3.0 and pycose 1.1.0 both reject it, and support is tracked in go-cose#224 and pycose#126. verax verify does not depend on either library.

Verifiers other than ours

test-vectors/ is a frozen set of ledgers, each with the verdict and the stage a verifier should report. Two people have run the set at vectors-v1 with verifiers of their own and posted the results:

• Tymofii Pidlisnyi (Agent Passport System), with a runner in the APS conformance suite: a partial, stage-by-stage comparison across all 16 vectors, not a whole-ledger verdict (run).
• Roberto Locatelli (cryptovalid-opencore), with clean-room checkers written from the drafts, the RFCs and the vector README: with the checkpoint verified under the witness key, 16 of 16 verdicts and 15 of 16 first failing stages. One of those matches came from a rule added after reading the vector, as the run itself states (run).

A matching run shows that another verifier reads these encodings and reaches the same verdict at the same stage. It is not an independent audit of the body.

Install

npm install -g @verax-ai/bodyverax --helpverax doctor

A host that cannot reach the npm registry can install from an offline bundle; the steps are in docs/OFFLINE_INSTALL.md.

On an account where every process is elevated (the built-in Administrator, or EnableLUA=0), a command from a user-writable npm prefix is refused; use the administrator-owned copy at %ProgramFiles%\verax-cli.

Node 22.6 or newer. The body speaks MCP over Streamable HTTP at /mcp on VERAX_BIND (default 127.0.0.1:8787) and needs an issuer, a JWKS URL, an audience, a state directory and a policy file before it listens; verax doctor names what is missing. The variables and the run steps are in packages/body/README.md.

Tools

The policy decides which of these a token's scopes may call; packages/proxy/policy/default.json denies what it does not name.

What the body does beyond the gate

Each line below is a row in the capability matrix in docs/STATUS.md, where it is stated against a version, with what it does not do and the test that fails when it stops being true.

• Approval: a held call is approved with verax approve on this machine, or through the operator door from another device with a passkey and an assertion for that request; the door is off unless an origin is named for it. On Windows the CLI approve runs from a separate administrator account. The passkey panel behind verax desktop is not released yet. The approver's operator id is bound into the signed record by hash.
• Witness: verax witness signs effect rows from a second process and writes durable checkpoints; without it the witness class stays self.
• Halt and revoke: verax halt turns every further call into a signed deny; a revoked token id is refused before any record is written.
• Reconcile: verax reconcile matches recorded spends against a card statement export and names the matched, ghost and authorized-but-unpaid rows.
• Tenant key: memory and inbox are stored under a key derived from the token's issuer and subject; another tenant's id is answered with a signed deny.
• Bounds: rate and daily counters, a disk-low refusal (HTTP 507) when a deny could not be recorded, and an egress allow-list; counters that cannot be read fail closed.
• Doctor and heartbeat: verax doctor names what is missing or stale before the first call finds out.

Watch for silence

The running body pulses even while idle (10 s by default; VERAX_HEARTBEAT_EVERY_MS, minimum 1,000 ms). Start rows in starts.jsonl record gaps from the previous beat; verax verify <stateDir> summarizes them offline. Since 0.5.0 start rows are signed by the record key.

verax watch ./verax-state --max-silence 30sverax watch ./verax-state --onceverax watch --url https://host/healthz --token-file ./audit.token --onceverax watch ./verax-state --on-silence exec --exec "node isolate.mjs"

An unreadable, stale or far-future beat is silence. A local watch halts by default; recovery never resumes it. An operator must use the existing resume path. Remote watch reports silence and cannot halt remotely. Tokens are read only from files; HTTPS is required except on loopback. An exec command runs once per silence episode with VERAX_WATCH_REASON in its environment, without a shell. Quote executable/arguments containing spaces. --once exits 0 live, 3 silent or 2 on usage errors. Continuous watch prints one JSON line per silence episode and recovery, polling at max-silence/3. Run it where the operator chooses; a same-host watcher shares that host's trust and is not independent evidence if both ledger and watcher vanish.

Connect a client

The body listens on http://127.0.0.1:8787/mcp by default. A client configuration looks like this; the token comes from your issuer.

{  "mcpServers": {    "verax": {      "url": "http://127.0.0.1:8787/mcp",      "headers": { "Authorization": "Bearer <token from your issuer>" }    }  }}

Status

What the tree carries and what stays unproven is stated, item by item, in docs/STATUS.md. Nothing in this repository is a claim beyond that file, and a paragraph there is not a release. The threat model is in docs/THREAT_MODEL.md; how to report a vulnerability is in SECURITY.md.

What else is in the tree

• apps/panel is the account-for screen: the records list, the black box and the status view, read from the signed ledger. Private; it is not published. The panel session uses the code flow; the access token stays in memory and is dropped on refresh. Vite may still attach VERAX_DEV_TOKEN from .env.local to /api when the request has no Authorization header (desktop MCP brains and tests).
• scripts/dev-issuer.mjs is development only; not a production authorization server. It serves GET /authorize (PKCE S256) and POST /token, writes a token to --out, and never prints one. It listens on VERAX_DEV_ISSUER_PORT (default 8790). NODE_ENV=production exits.
• scripts/demo-box.mjs is development only: one process that starts the dev issuer and the body on loopback with a temporary ledger, mints itself a short-lived token through the issuer's code flow, and speaks MCP over stdio for a sandbox that cannot hold a token of its own, such as a directory's build check. The body is not changed by it: every call still passes the gate and is recorded, spend is always held, and no operator is there to approve it. NODE_ENV=production exits. Not a deployment.

Developing

npm cinpm test            # guards, build, typecheck, unit and cost suites, panelnpm run pack:smoke  # pack the three packages and install them elsewhere

CI runs the suite as a non-root user on Linux and again on Windows, plus the proxy performance check. Releases go out from the Actions tab: release.yml publishes the three packages with npm trusted publishing and a provenance attestation, then mcp-registry.yml updates the registry record once npm answers for the new version. Neither runs on push.

Tested on every release on the platforms listed in docs/PLATFORMS.md, each row linked to its CI run.

To contribute, or to report a run on a platform that is not listed, see CONTRIBUTING.md.

License

Apache-2.0.