VERAX README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the VERAX listing page.
Verax
The body an agent asks before it acts.
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 on this machine approves it. 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.
By VERAX Teknoloji. Sister projects: Conarium · Tugra · Cedulon. Decision records use the Cedulon record format.
See it run
The recording is the output of one run in a terminal where the approval
question was answered y. 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:
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).
--keep leaves the temporary ledger on disk. verax verify <dir> reads it
back without a body, as in Read the ledger back without us.
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, in 0.4.0, an elevated CLI approve is the way to approve (the passkey panel ships in 0.4.1). 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):
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:
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. The passkey panel (verax desktop) is not in 0.4.0; it ships in 0.4.1. 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:
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. 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:
What ships
| Package | What it is |
|---|---|
@verax-ai/body | The MCP server and the verax command: serve, install, uninstall, init, doctor, approve, operator, reconcile, witness, halt, unlock (desktop ships in 0.4.1). |
@verax-ai/proxy | The decision proxy the body is built on: policy, signed records, ledger, explain, reconcile. |
@verax-ai/inventory | The roster document a body serves and the panel lists, with its strict parser. |
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 four
things separately, because they fail separately:
That last pair of lines 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.
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.
Install
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.
| Tool | Description |
|---|---|
memory.get | Reads one memory item behind the gate, stored per tenant. |
memory.put | Writes one memory item behind the gate, stored per tenant. |
audit.explain | Reads a decision back from the signed ledger, with its chain, its signatures and its findings. |
message.read | Reads the inbox. |
message.send | Writes to the outbox; reaches only hosts the policy allow-lists. |
spend | Authorizes a payment and records it, under a cap, a payee list and a daily limit from the policy; held for an operator when the policy says so. The body does not move money. |
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: in 0.4.0 a held call is approved with
verax approveon this machine. On Windows that runs from a separate administrator account. The passkey panel (verax operator,verax desktop) ships in 0.4.1. The approver's operator id is bound into the signed record by hash. - Witness:
verax witnesssigns effect rows from a second process and writes durable checkpoints; without it the witness class staysself. - Halt and revoke:
verax haltturns every further call into a signed deny; a revoked token id is refused before any record is written. - Reconcile:
verax reconcilematches 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 doctornames what is missing or stale before the first call finds out.
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.
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/panelis 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 attachVERAX_DEV_TOKENfrom.env.localto/apiwhen the request has no Authorization header (desktop MCP brains and tests).scripts/dev-issuer.mjsis development only; not a production authorization server. It servesGET /authorize(PKCE S256) andPOST /token, writes a token to--out, and never prints one. It listens onVERAX_DEV_ISSUER_PORT(default 8790).NODE_ENV=productionexits.scripts/demo-box.mjsis 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,spendis always held, and no operator is there to approve it.NODE_ENV=productionexits. Not a deployment.
Developing
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.
License
Apache-2.0.