HESO ships as four packages, all at version 0.1.0. They share one Rust core, so a verdict is byte-identical whether it runs on your server or in a reviewer’s browser. You never re-implement crypto in Python or JavaScript. Install the one that matches the job: capturing an agent’s actions, verifying receipts and talking to the cloud, or verifying client-side. Not sure which? Skip to Which one do I need?
Python SDK
The heso package is the gating SDK: decorators and a transparent proxy that capture every action your agent takes, evaluate it against policy, gate it, and sign it into a receipt. Install it with pip or uv.
# pippip install heso # uvuv add heso
Then scaffold a project. heso init writes a heso_bootstrap.py, gitignores the local data directory, and asks the Rust engine to mint your operator identity and write a starter heso.toml. Run it as many times as you like — an existing key and policy are left as-is.
heso initThe heso package bundles the Rust core as the heso._core wheel and runs it in-process — no subprocess for gate operations. The heso-compliance engine runs only during heso init, to mint identity and the starter policy. After that, gating, signing, and the audit chain all run inside your process.
Next: the Python quickstart gates a real action end to end, or read the full Python SDK reference for the decorators, wrap(), and the suspend/resume layer.
TypeScript & Node
The @hesohq/sdk package is the TypeScript surface for verifying receipts and talking to the cloud control plane: gating helpers, the cloud client, and the wire types. It depends on @hesohq/core, the native addon that does the actual verify, sign, redact, and key work.
pnpm add @hesohq/sdk# npm i @hesohq/sdk# yarn add @hesohq/sdk
@hesohq/core is built with napi-rs and ships prebuilt native binaries for darwin, linux, and win as optionalDependencies. Your package manager pulls the right one for the host, so there is no compile step. Both packages target Node 18 or newer and ship CommonJS.
import { configure, gate, assertGate } from "@hesohq/sdk" configure(process.env.HESO_API_KEY!, process.env.HESO_ENDPOINT!) // throws unless the receipt verifies at >= L0assertGate(receiptBytes)
Use @hesohq/sdk to verify receipts and call the cloud API from Node. To capture and gate your own agent — the decorators and proxy — use the Python SDK. In Node you construct and verify receipts with @hesohq/core; there is no Node decorator surface.
Next: the TypeScript quickstart verifies a receipt and enforces a minimum trust level, or see the @hesohq/sdk reference.
Browser verifier
The @hesohq/verify-wasm package is the verify-only WASM surface — the same package the HESO web console uses to check receipts in the browser. It is ESM only, built with wasm-bindgen for the web target, and it holds no private key: there is no signing in the browser.
pnpm add @hesohq/verify-wasmThe default export is an async init that fetches the .wasm file, so your app must serve the .wasm. Await init() once before you call anything; after that, the named exports such as verifyActionReceipt run synchronously. Cache the init promise and reuse it.
import init, { verifyActionReceipt } from "@hesohq/verify-wasm" await init() // fetches the .wasm once; cache the promiseconst verdict = verifyActionReceipt(receiptBytes) // { verdict, trust_level }
Serving the .wasm file and wiring up init() in the App Router has a few bundler gotchas. The Next.js guide walks through loading the verifier client-side, and Quickstart: Verify in the browser checks a receipt with no HESO infrastructure at all.
Which one do I need?
Match the package to what you are doing. Capturing and gating your own agent is the Python SDK; everything else is verification or cloud access. All four are at 0.1.0 and call the same Rust core.
| Package | Runtime | What it does |
|---|---|---|
heso | Python ≥ 3.10 | Gate, sign, and audit an agent’s actions — the decorators and proxy. |
@hesohq/sdk | Node ≥ 18 | Verify receipts and talk to the cloud control plane (the cloud client). |
@hesohq/core | Node ≥ 18 (native) | The native verify, sign, redact, and key surface that @hesohq/sdk builds on. |
@hesohq/verify-wasm | Browser | Verify-only WASM — re-run the math client-side, no private key, no network. |
For a deeper map of the family — one core, four surfaces — see the SDK overview.
Requirements
- Python 3.10 or newer for the
hesopackage (the Rust core is bundled as a wheel, so no toolchain is needed). - Node 18 or newer for
@hesohq/sdkand@hesohq/core. The native binaries are prebuilt for darwin, linux, and win, so there is no compile step on supported platforms. - A modern browser with WebCrypto for
@hesohq/verify-wasm— used both to verify receipts and to sign approvals client-side.
Installing a package gives you the tools to capture, sign, and verify actions. On its own it proves nothing about your agent. Proof comes from the receipt: it shows the operator authorized an action under a known policy, and at L1 that a person approved it with a device-held key — the record of what was authorized and by whom, not whether the action succeeded downstream.
Next steps
You are installed. Pick a quickstart and gate, verify, or check a receipt end to end.