The heso command is installed with the Python SDK. It sets a project up: it writes a bootstrap module, ignores the local data directory, and asks the Rust engine to mint your operator identity and write a starter policy. After that, your code gates calls with the decorators or the proxy — nothing on the command line is needed at runtime.
Install
The console script comes with the heso package. It needs Python 3.10 or newer and bundles the Rust core as an in-process wheel, so checking a request against your policy needs no separate binary or subprocess.
pip install hesoConfirm the script is on your path:
heso --helpFor the full Python surface — heso.init(), the decorators, the proxy, and the suspend/resume layer — see the Python SDK reference.
heso init
heso initcommand
Scaffold a HESO project: write the bootstrap module, gitignore the local data directory, and delegate to the Rust engine to mint the operator identity and write a starter heso.toml.
heso init [dir]Parameters
- dirpath
- The directory to scaffold. Defaults to the current working directory. The directory is created if it does not exist.
Example
# scaffold the current directoryheso init # or scaffold a named project directoryheso init my-agent
What it writes:
heso_bootstrap.py— a one-line module that callsheso.init(). See the bootstrap module below.- A
.gitignoreentry for the local data directory, which holds the minted key, the audit log, and the outbox queue. None of that is ever committed. - A starter
heso.toml, written by the Rust engine — see the engine.
A scaffolded project looks like this:
my-agent/ heso_bootstrap.py # import heso; heso.init() heso.toml # starter policy, written by the Rust engine .gitignore # ignores the local data dir (minted key, audit log, outbox)
heso init is safe to re-run. An existing operator key and an existing heso.toml are left as-is, so you will not overwrite a minted identity or a policy you have edited.
The bootstrap module
heso init writes heso_bootstrap.py. It is one call: heso.init() resolves and installs your config, which every decorator and the proxy read from.
import heso heso.init()
Import this module once at process start, at the very top of your entrypoint, so the config is installed before the rest of your program runs and the first gated call has it ready:
# import the bootstrap once, at the very top of your entrypointimport heso_bootstrap # noqa: F401 from my_agent import runrun()
Importing heso_bootstrap at the top of your entrypoint runs heso.init() before anything else, so the active config is in place by the time a decorator or the proxy gates its first call. You can also call heso.init() yourself instead of importing the module.
The engine
The Rust engine binary, heso-compliance, is the source of truth for identity and policy. It owns minting the operator identity and writing the starter policy template; the Python heso CLI delegates the init work to heso-compliance init.
Policy checks do not call this binary. The Rust core is bundled as the in-process heso._core wheel, so capturing, evaluating, signing, and verifying happen in-process with no subprocess. The engine binary runs only for the setup work it owns.
Config & the data directory
heso.init() builds your config by layering four sources, in order: explicit arguments, then environment variables, then a heso.toml it finds on disk, then defaults. The starter heso.toml that heso init writes is the file the engine finds — edit it to set what your agent is allowed to do.
The local data directory holds the minted operator key, the audit log, and the outbox queue. It is gitignored by heso init and never committed, so your signing key stays on the machine that minted it — the same property the cloud relies on for human approvals.
heso init gives you an operator identity and a starter policy. It does not configure the cloud control plane or human approval routing — that is your API key and the policy you write. Identity is local and offline; the cloud holds no signing key.