hesodocs
Start free

HESO developer docs

HESO gates, co-signs, and proves every action your AI agents take. Wrap an agent, and every action it takes — an LLM call, a tool call, a payment, a data export — is checked against your policy, signed into a receipt, and chained into a tamper-evident audit log (one where changes show up). Anyone can verify that receipt offline, in any browser, with no HESO infrastructure.

These docs cover everything: the Python SDK that gates your agent, the TypeScript and Node SDKs, the browser verifier, the policy language, and the cloud API. Everything is built on one Rust core, so a verdict is byte-identical whether it runs on your server or in a reviewer’s browser.

Start building

Pick the path that matches what you’re doing. Each quickstart is a complete, copyable walkthrough.

pip install hesoGate an agent (Python)Capture, gate, approve, sign, and audit a real action in ten lines.@hesohq/sdkVerify & gate (TypeScript)Check receipts and enforce a minimum trust level from Node.@hesohq/verify-wasmVerify in the browserRe-run Ed25519 + BLAKE3 locally — no account, no network.

What a receipt is

The unit of HESO is the Action Receipt: a signed JSON object that records exactly one action, the policy verdict that gated it, who approved it (if anyone), and a hash that pins the bytes. Here is one for a vendor payment that policy allowed:

receipt.json
{  "alg": "heso-action/v2+ed25519",  "content": {    "action_version": "heso-action/2.0",    "captured_at": "2026-01-14T18:04:31Z",    "agent_identity": "ed25519:uP3…b1",    "action": {      "verb": "payment",      "tool_name": "stripe.transfers.create",      "workflow": "vendor-payouts",      "account": "acct_19",      "fields": { "amount_usd": "4200", "payee": "Globex LLC" }    },    "policy": {      "rule_id": "pay-cap",      "rule_display": "Require approval to pay over $5,000",      "matched_conditions": [{ "field": "amount_usd", "op": "lte", "value": "5000" }],      "decision_path": "allow"    },    "trust_level": "L0",    "action_hash": "9f2c…e1c0"  },  "signatures": [    { "algorithm": "Ed25519", "key_id": "operator",      "public_key": "ed25519:uP3…b1", "signature": "3a9f…04af" }  ]}

The receipt carries an action_hash (BLAKE3 over its canonical bytes) and an Ed25519 signature. To verify it, you recompute the hash and check the signature — which is exactly what the browser verifier does, locally.

What a receipt proves — and what it doesn't

A receipt proves the operator authorized this action under a known policy, and — at L1 — that a person approved it with a device-held key. It records what was authorized — the action, the rule, the approver — not whether the action succeeded downstream.

Core concepts

New to the model? These nine pages explain how an action becomes verifiable evidence.

How HESO worksThe four-stage loop, end to end.Actions & verbsWhat gets captured for each action.Policy & decisionsallow · block · redact · require_approval.Trust levelsL0 operator vs L1 human co-sign.Action receiptsThe signed envelope, field by field.Offline verificationThe seven-gate verify order.

The SDK family

One Rust core (canonicalization, BLAKE3, Ed25519) compiled to four SDKs. You never re-implement the crypto in your own language — you call the SDK that fits your runtime.

hesoPython SDKDecorators + proxy to gate agents and tools in-process.@hesohq/sdkTypeScript SDKGating helpers, the cloud client, and wire types.@hesohq/coreNode coreNative verify, hashing, chains, redaction, keys.@hesohq/verify-wasmBrowser verifierThe verify-only WASM surface for any browser.
Reading order

If you’re evaluating HESO, read How HESO works then Trust levels. If you’re integrating, jump straight to a quickstart and keep the SDK reference open.