# Install the packages > Install the Probarion SDK, core and CLI 0.1.1 from npm on Node 24, or build them from source with pnpm 10, then check the build and import it. Install the SDK, core and CLI packages from npm for your own project, or build them from a clone for the repository's fixtures, scripts and evaluation. Then check that they work and import the SDK. Status: Live · Network: Testnet and Mainnet · Reviewed: 2026-11-11 · Built from: 4ab41ca1436589c22073fa842ee46f970415e3d5 Canonical page: https://probarion.xyz/docs/build/install 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](https://probarion.xyz/docs/start/evaluate-in-5-minutes.md). > **On npm** > > Release 0.1.1 of `@probarion/core`, `@probarion/sdk` and `probarion` is on npm, under the `latest` tag. It was published on 2026-11-11 from the tag `sdk-v0.1.1` on `main`, by the repository's release workflow, with npm provenance. Release 0.1.0 came out on 2026-11-09. The packages are an unaudited beta, and a 0.x minor release may change their API. ## 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: ```bash 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: ```bash 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: ```bash npm install @probarion/core ``` For the CLI, install it globally and check its version: ```bash npm install -g probarion probarion --version ``` ```text 0.1.1 ``` Or run it without installing, from your project's folder, as `npx probarion` followed by the command: ```bash 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](https://github.com/probarion/probarion/tree/main/packages/mcp) sets it up for each MCP client. ## Build from source 1. **Open a shell in the folder where you keep projects.** The clone goes into a new `probarion` folder there. 2. **Run the lines of one tab, in order.** The "Everything" tab starts after the clone: for it, run the first line of "Packages only" first, then the lines of "Everything". **Packages only** ```bash git clone https://github.com/probarion/probarion cd probarion pnpm install pnpm --filter "{packages/cli}..." build ``` **Everything** ```bash cd probarion pnpm install --frozen-lockfile pnpm build ``` "Packages only" clones the repository, installs, and builds the CLI together with the packages it depends on, `@probarion/core` and `@probarion/sdk`, in build order. The proof page, the security page and the console's CLI fallback need none of this: they print `npx probarion` commands. Only a mainnet pre-ledger check on the proof page also reads the repository's evidence files, so for it the page says to clone the repository first. "Everything" is the build from the repository README. It installs exactly what the committed lockfile names, and its `pnpm build` builds every package of the workspace, the Next.js website in `apps/web` included. The README timed that route at about three and a half minutes on a first install: 2 min 42 s to install, 34 s to build. 3. **Update an older clone.** The CLI and your scripts run the built files in each `dist` folder, which change only when you build. In the `probarion` folder, pull, install and run the build line again (`pnpm build` instead, if you used the "Everything" tab): ```bash git pull pnpm install pnpm --filter "{packages/cli}..." build ``` ## 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: ```bash node packages/cli/dist/bin.js --version ``` ```text 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: ```bash node packages/cli/dist/bin.js --help ``` ```text Usage: probarion [options] [command] Spend by mandate. Prove every payment. (Unaudited beta.) Options: -V, --version output the version number --network mainnet | testnet (default: NEAR_NETWORK, else testnet) --rpc 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 `. The [CLI README](https://github.com/probarion/probarion/blob/main/packages/cli/README.md) 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: ```bash 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. ```text 9 passed, 0 failed, 0 unproven RESULT: PASS ``` [Verify a vault yourself](https://probarion.xyz/docs/trust/verify-a-vault.md) 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: | Package | Entry point | From npm | From the root of a clone | | - | - | - | - | | `@probarion/sdk` | `.` | `@probarion/sdk` | `./packages/sdk/dist/index.js` | | `@probarion/sdk` | `./testing` | `@probarion/sdk/testing` | `./packages/sdk/dist/testing/index.js` | | `@probarion/core` | `.` | `@probarion/core` | `./packages/core/dist/index.js` | 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. `read-vault.mjs` ```js 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" })); ``` ```bash 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](https://probarion.xyz/docs/start/evaluate-in-5-minutes.md) also warns: ```text 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`](https://probarion.xyz/docs/build/errors.md#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](https://github.com/probarion/probarion/blob/main/packages/sdk/README.md) notes. ## Configure [`.env.example`](https://github.com/probarion/probarion/blob/main/.env.example) 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. | Variable | Read by | What it sets | | - | - | - | | `NEAR_NETWORK` | CLI | The network when `--network` is not given: `mainnet` or `testnet`. Unset: `testnet`. The SDK takes `network` as an option. | | `NEAR_RPC_URLS` | SDK, CLI | Comma-separated RPC URLs, in failover order. The SDK's `rpcUrls` option and the CLI's `--rpc` take precedence. Unset: the network's default RPCs. | | `NEAR_ARCHIVAL_RPC_URLS` | SDK, CLI `verify` | Archival RPCs for burn transactions older than about 2.5 days. The CLI's `--archival-rpc` takes precedence. Unset: FastNEAR's archival node for the network. | | `PROBARION_VAULT_ID` | CLI | The default for `--vault`. The SDK takes `vault` as an option. | | `PROBARION_FACTORY_ID` | CLI `vault create` | The factory that creates the vault. Unset: the network's factory. | | `PROBARION_LEDGER_PATH` | SDK, CLI `verify` and `ledger export` | The ledger file. Unset: `.probarion/ledger.jsonl` in the working directory. | | `PROBARION_AGENT_KEY` | CLI `check` | The SDK does not read it: your code passes it as `agentKey`. Without `--agent-pk`, `check` checks as the public key of this secret, and never prints the secret. | | `PROBARION_LEDGER_KEY` | Neither | Your code passes it as `ledgerKey`. | | `NEARAI_API_KEY` | Neither | Your code passes it as `model.apiKey`, for the optional model step. With `model: null` the code decides alone. | | `NEARAI_MODEL` | SDK | The NEAR AI Cloud model when `model.model` is not given. | > **One setting for both networks** > > `NEAR_RPC_URLS` and `NEAR_ARCHIVAL_RPC_URLS` replace the RPCs of whichever network you pass, and `.env.example` sets both to testnet URLs. With those values, a run with `--network mainnet` still talks to testnet RPCs, since nothing in the packages checks which chain an RPC serves. This follows from the code; no test shows it yet. Unset both, or set mainnet URLs, before a mainnet run. `.env.example` also sets `PROBARION_FACTORY_ID` and `PROBARION_VAULT_ID` to testnet accounts, which the CLI uses on any network: with them, `vault create` targets the testnet factory and the other commands default to the testnet vault. Unset them too, or set mainnet values. The `_MAINNET` and `_TESTNET` names in `.env.example` are for the web app only: the SDK and the CLI read the unsuffixed names. NEAR testnet is live today. On mainnet one small vault runs, `v0.probarion.near`, and no mainnet factory is deployed: see [Testnet and mainnet](https://probarion.xyz/docs/start/testnet-and-mainnet.md). ## 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](#configure). ## Next steps - [Developer quickstart](https://probarion.xyz/docs/start/developer-quickstart.md): 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](https://probarion.xyz/docs/build/let-an-agent-pay.md): the choices a production payment loop makes. - [Verify a vault yourself](https://probarion.xyz/docs/trust/verify-a-vault.md): run the verifier on a live vault and read its report. - [Errors](https://probarion.xyz/docs/build/errors.md): the vault, SDK and HTTP error codes. - [What works today](https://probarion.xyz/docs/start/what-works-today.md#npm-release-011): the status of each part, the npm release included. - [For AI agents](https://probarion.xyz/docs/resources/for-ai-agents.md): the rules for an agent that builds on Probarion. - The [CLI README](https://github.com/probarion/probarion/blob/main/packages/cli/README.md) and the [SDK README](https://github.com/probarion/probarion/blob/main/packages/sdk/README.md) list every command and the rest of the API.