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.