hero_lib_rhai

Rhai scripting bindings for the herolib libraries. Each crate in crates/*_rhai exposes a corresponding herolib module as a Rhai namespace. The hero_do binary embeds the Rhai engine and loads all modules, giving you a scriptable CLI for the entire herolib ecosystem.

---

hero_do

Build

Always use the provided script — do not use cargo build directly:

./build_herodo.sh

Run a script

hero_do my_script.rhai
hero_do examples/scheduler/01_basic.rhai

Shebang support

Make any .rhai file directly executable:

#!/usr/bin/env hero_do

print("Hello from hero_do!");

chmod +x my_script.rhai
./my_script.rhai

---

Available modules

Module	Description
herolib-core	Text processing, networking, HeroScript
herolib-os	OS operations, process management, git, virtualisation
herolib-crypt	Encryption and key management
herolib-clients	Redis, PostgreSQL, MQTT, Mycelium, Hetzner
herolib-ai	AI client (Groq, OpenRouter, SambaNova)
herolib-vault	Secret vault management
herolib-code	Rust builder utilities
herolib-mos	MOS module
herolib-virt	Virtualisation
herolib-proc	Process supervisor (hero_proc): services, jobs, logs

---

Import system

hero_do extends Rhai's import statement to support local files, directories, HTTP URLs, and a GitHub shorthand.

import "lib/math" as m; // local file (no extension needed)
import "lib" as l; // whole directory — all .rhai files merged
import "https://example.com/utils" as u; // HTTPS URL
import "github:user/repo/scripts/helpers" as h; // GitHub raw shorthand

Relative paths resolve relative to the calling script's location. HTTP and GitHub results are cached for the engine session.

Directory imports

When you import a directory, all .rhai files inside are sorted alphabetically, merged, and exposed as a single namespace.

---

run()

run() executes another script in full (with its own scope), unlike import which loads a namespace.

run("other.rhai"); // relative to calling script
run("https://example.com/setup.rhai"); // from HTTP
run("github:myorg/repo/scripts/setup"); // from GitHub

---

Built-in scheduler

Register tasks at any interval; the scheduler checks every 50 ms.

every(30, "sec", || { print("every 30 seconds"); });
every(5, "min", || { print("every 5 minutes"); });
every(1, "hour", || { print("every hour"); });
every(500,"ms", || { print("every 500 ms"); });

scheduler_run(); // block forever (Ctrl+C to stop)
scheduler_run_for(60); // block for 60 seconds then return
scheduler_stop(); // stop from inside a task

Time units accepted: ms / millisecond / milliseconds, s / sec / second / seconds, m / min / minute / minutes, h / hour / hours.

Tasks run immediately on the first tick, then repeat at the given interval. Closures capture variables by reference, so state persists across ticks.

---

Workspace crate layout

crates/
 ai_rhai/ — Rhai bindings for herolib_ai
 clients_rhai/ — Rhai bindings for herolib_clients
 code_rhai/ — Rhai bindings for herolib_code
 core_rhai/ — Rhai bindings for herolib_core
 crypt_rhai/ — Rhai bindings for herolib_crypt
 gpu_agent/ — daemon binary run inside VastAI containers (see docs/gpu_agent.md)
 hero_do/ — CLI binary embedding the Rhai engine
 hero_runner_rhai/ — CLI lifecycle binary (--start/--stop, hero_proc registration)
 hero_runner_rhai_server/ — Fork-based Rhai script runner with OpenRPC and SSE log streaming
 hero_runner_rhai_admin/ — Web dashboard for the runner (Bootstrap 5, /rpc proxy, SSE)
 mos_rhai/ — Rhai bindings for herolib_mos
 os_rhai/ — Rhai bindings for herolib_os
 proc_rhai/ — Rhai bindings for hero_proc (process supervisor)
 vault_rhai/ — Rhai bindings for herolib_vault
 virt_rhai/ — Rhai bindings for herolib_virt

---

Examples

See examples/ for runnable scripts covering imports, scheduling, and process supervision.

For the fork-based Rhai runner service (server + UI + lifecycle CLI), see docs/hero_runner_rhai.md.