Install the packages

This page installs three Probarion packages, @probarion/core, @probarion/sdk and the probarion CLI, at version 0.1.1 from npm. Install them from npm to use them in your own project. Build them from a clone of the repository to run the repository's fixtures, scripts and tests, or the evaluation.

Requirements#

• Node.js 24 or newer. The engines field of every package says node >=24, and the repository's .nvmrc names 24, for a version manager that reads it.
• ES modules. The packages are ESM only, with no CommonJS build: load them with import.
• bash, zsh or PowerShell. Each command sits on its own line, so Windows PowerShell 5.1, which has no &&, runs them too.

A build from source also needs:

• pnpm 10. The root package.json accepts pnpm >=10 <11 and names pnpm@10.34.9 as its package manager.
• git, for the clone.

Optional: @nearai/inference-sdk, which only the online attestation check uses (verify --online in the CLI, verify({ online: true }) in the SDK), needs Node 24.22.1 or newer. The CLI lists it as an optional dependency, so npm, and pnpm install in a clone, install it with the CLI, unless they cannot: an optional dependency that fails to install is left out. The SDK lists it as an optional peer dependency, which npm does not install: add it to your project to run the online check from your code. Everything else runs on any Node 24.

You need no Rust, wallet, NEAR account or key to install or build. Rust is needed only for the contracts: the contract tests that pnpm verify runs, the contract build (pnpm contracts:build, with cargo-near) and the sandbox tests (pnpm test:sandbox).

Check your versions first. node --version prints v24 or later, and, for a build from source, pnpm --version prints a 10.x version:

node --version
pnpm --version

Install from npm#

In your project's folder, install the SDK and the core library together, since the SDK's examples import from both:

npm install @probarion/sdk @probarion/core

For the core library alone, with the policy engine, the ledger and the verifier's checks and no network code:

npm install @probarion/core

For the CLI, install it globally and check its version:

npm install -g probarion
probarion --version

0.1.1

Or run it without installing, from your project's folder, as npx probarion followed by the command:

npx probarion --help

npx probarion also runs at the root of a clone, whose own package.json is named probarion-monorepo. There it runs release 0.1.1 from npm, not the code in the clone. To run the CLI a clone builds, use node packages/cli/dist/bin.js, as the rest of this page does.

The CLI's commands are the same however you run it: probarion verify --help from npm is node packages/cli/dist/bin.js verify --help in a clone. To sign what the CLI prints, you also need near-cli-rs, the near command.

The MCP server @probarion/mcp is on npm from 0.1.1 too, and the official MCP registry lists it as io.github.probarion/probarion. It runs as npx -y @probarion/mcp@0.1.1, with no clone and no global install, and its README (opens in a new tab) sets it up for each MCP client.

Build from source#

Check the build#

Run these from the root of the clone. None of them needs a key or a wallet, and none sends anything.

The version. A clone builds the version in packages/cli/package.json, which can be ahead of the release on npm:

node packages/cli/dist/bin.js --version

0.1.1

The commands. The help lists the program options and the commands. This output was captured through a pipe, so its lines wrap at 80 columns; a terminal wraps them to its own width:

node packages/cli/dist/bin.js --help

Usage: probarion [options] [command]

Spend by mandate. Prove every payment. (Unaudited beta.)

Options:
  -V, --version        output the version number
  --network <network>  mainnet | testnet (default: NEAR_NETWORK, else testnet)
  --rpc <urls>         comma-separated NEAR RPC URLs (default: NEAR_RPC_URLS,
                       else the network defaults)
  -h, --help           display help for command

Commands:
  vault                vault commands (owner transactions are printed, never
                       signed)
  mandate              mandate commands (owner transactions are printed, never
                       signed)
  agent                agent keys
  ledger               ledger commands
  spend                spend commands (transactions are printed, never signed)
  check [options]      dry-run check_spend for an invoice: a free view call;
                       nothing is signed or sent
  verify [options]     verify a vault's ledger signatures, hash links, anchors,
                       decisions, attestations, keys, burn memos and factory
                       version
  help [command]       display help for command

Each command has its own help, such as node packages/cli/dist/bin.js verify --help. Program options can come before the command, as the console writes node packages/cli/dist/bin.js --network testnet vault create ..., or after it, as the proof page writes verify --network testnet --vault <vault>. The CLI README (opens in a new tab) describes every command.

The offline verifier. The fixture is a committed snapshot of a ledger and its chain state, signed with test keys. It is not a live vault, and the check reads no network:

node packages/cli/dist/bin.js verify --offline packages/core/test/fixtures/valid-snapshot.json

The report starts with Probarion verify: x.vaults.probarion.testnet (testnet) and the time it ran, gives checks a to i a PASS each, and ends with these lines. The command exits 0.

9 passed, 0 failed, 0 unproven
RESULT: PASS

Verify a vault yourself runs verify on a live vault.

Use the SDK from your code#

With the packages from npm, your code imports them by name, as in import { Probarion } from "@probarion/sdk";. A script in the root of a clone imports the built files by path instead:

Each entry point has its type declarations beside it. To import @probarion/sdk/testing from TypeScript, set "moduleResolution" to "NodeNext" or "Bundler". ./testing holds test doubles: a fake chain, a fake NEAR JSON-RPC server and a fake NEAR AI Cloud. A test that passes against them does not show that a real vault behaves the same.

The importing file must be an ES module: an .mjs file, or a .js file under a package.json that sets "type": "module". The root package.json of the clone sets it, so a .js or .mjs file in the root of the clone is an ES module.

A read-only example. This is step 4 of the README's evaluation, saved as a file in the root of the clone. With the packages from npm, save it in your project and make its first line import { Probarion } from "@probarion/sdk";. An instance with no keys and model: null lists the mandates of the testnet vault v0.probarion.testnet and dry-runs a spend of 2 USDC and one of 6 USDC with the contract's free check_spend view. It signs nothing and sends nothing.

import { Probarion } from "./packages/sdk/dist/index.js";
const vault = new Probarion({ network: "testnet", vault: "v0.probarion.testnet", model: null });
for (const m of await vault.mandates.list())
  console.log(`mandate ${m.id} "${m.label}": ${m.status}, pays ${m.payee.account_id ?? m.payee.address}, at most ${m.max_per_payment} per payment`);
const invoiceHash = "ab".repeat(32);
console.log("2 USDC:", await vault.checkSpend({ mandateId: 1, amount: "2000000", invoiceHash, ref: "README-1" }));
console.log("6 USDC:", await vault.checkSpend({ mandateId: 1, amount: "6000000", invoiceHash, ref: "README-1" }));

node read-vault.mjs

The repository README records this output. The script reads the live vault, so its output changes when the vault changes or when its mandates expire, as Evaluate in 5 minutes also warns:

mandate 1 "smoke near": active, pays probarion-payee.testnet, at most 5000000 per payment
mandate 2 "smoke base": active, pays 0x1111111111111111111111111111111111111111, at most 5000000 per payment
2 USDC: { ok: true, code: null, would_hold: false }
6 USDC: { ok: false, code: 'OverPerPayment', would_hold: false }

Amounts are strings in USDC base units, with 6 decimals, so "2000000" is 2 USDC. Mandate 1 allows at most 5 test USDC per payment, so the contract accepts 2 and refuses 6, until the mandate expires.

The smoke mandates expire on 2026-12-01, 30 days after the 2026-11-01 smoke run that created them. After that both dry runs should answer MandateExpired, because the contract checks expiry before the per-payment limit, and mandates.list() still prints active, since a mandate's status does not count its expiry. This follows from the contract's code; no test shows it on this vault yet.

Run the SDK in Node, on your server: its default ledger store is a file, and the agent and ledger keys stay server-side. The SDK is an unaudited beta, and a 0.x minor release may change its API.

In a clone, a package of the clone's pnpm workspace that depends on the SDK also imports it by name, as the SDK README (opens in a new tab) notes.

Configure#

.env.example (opens in a new tab) lists these variables for the SDK and the CLI, most with a comment. The Read by column says which package reads each one from the process environment. Where the SDK does not read one, your code reads it and passes the value as an option, such as network, vault, agentKey, ledgerKey or model.apiKey. Neither package loads a .env file by itself: set the variables in the shell that runs your code, or pass the values as options. An empty value counts as unset.

NEAR testnet is live today. On mainnet one small vault runs, v0.probarion.near, and no mainnet factory is deployed: see Testnet and mainnet.

Common mistakes#

• An engines or version error during the install. The packages need Node 24 or newer, and a build from source needs pnpm 10 too. Check node --version and pnpm --version.
• A script cannot load the packages. There is no CommonJS build. Load them with import from an ES module: an .mjs file, or a .js file under a package.json that sets "type": "module", as the root of the clone does.
• TypeScript cannot find @probarion/sdk/testing. Set "moduleResolution" to "NodeNext" or "Bundler" in your tsconfig.json.
• npx probarion answers "could not determine executable to run". It ran at the root of an older clone, whose own package.json was still named probarion. Run git pull in the clone, run it from your project's folder, or, in the clone, run node packages/cli/dist/bin.js.
• Node cannot find packages/cli/dist/bin.js. Run the CLI from the root of the clone, after the build line. The dist folders exist only after a build.
• The build takes long. pnpm build builds the website too. For the SDK and the CLI alone, run pnpm --filter "{packages/cli}..." build.
• An older clone acts on old code. Pull, then run pnpm install and the build line again, as in step 3 of the build.
• An owner command the CLI printed fails in cmd.exe. The printed commands are written for bash, zsh and PowerShell, and the CLI says so under each one: "Run it in bash, zsh or PowerShell (not cmd.exe)."
• A mainnet run reads testnet. NEAR_RPC_URLS still holds the testnet URL from .env.example, or PROBARION_FACTORY_ID and PROBARION_VAULT_ID still name the testnet accounts from it. See Configure.

Next steps#

• Developer quickstart: one payment on testnet. Its step 1 is this build: with the clone built, start at its step 2, in the probarion folder.
• Let an agent pay: the choices a production payment loop makes.
• Verify a vault yourself: run the verifier on a live vault and read its report.
• Errors: the vault, SDK and HTTP error codes.
• What works today: the status of each part, the npm release included.
• For AI agents: the rules for an agent that builds on Probarion.
• The CLI README (opens in a new tab) and the SDK README (opens in a new tab) list every command and the rest of the API.