How the Rhai Scripting Engine Powers .ragsh Workflow Tools in OpenHuman

OpenHuman embeds the Rhai scripting engine to execute .ragsh workflow files in-process, enabling low-latency automation pipelines that directly invoke agent tools, memory APIs, and HTTP clients through a sandboxed Rust integration.

The OpenHuman platform implements its automation pipelines using Rhai, an embeddable scripting language designed for Rust. Files ending in .ragsh contain workflow definitions written in Rhai syntax that execute within a customized engine, granting users programmable control over agent tools and external services while maintaining the safety and performance of native Rust code.

Understanding the .ragsh Workflow Architecture

OpenHuman treats .ragsh files as first-class automation citizens. When a user creates a workflow, the system stores the .ragsh file under the workspace’s flows/ directory and loads it through the flows domain module.

Workflow Registration and Discovery

The entry point for all workflow operations resides in src/openhuman/flows/mod.rs. This module discovers .ragsh files within the workspace and registers them for execution. The core loader reads the script content and prepares it for the Rhai compiler, establishing the link between the file system and the embedded scripting runtime.

AST Parsing and Compilation

Once loaded, the raw script content moves to src/openhuman/flows/rhai/engine.rs where it undergoes compilation. The engine invokes rhai::Engine::compile to transform the .ragsh source into an Abstract Syntax Tree (AST). This compilation step validates syntax and produces an executable representation that the Rust runtime can evaluate efficiently without re-parsing during execution.

Inside the Custom Rhai Engine

OpenHuman does not use a stock Rhai installation. Instead, it constructs a specialized engine instance configured specifically for workflow automation and security constraints.

Engine Construction and Sandboxing

The initialization logic in src/openhuman/flows/rhai/engine.rs applies strict resource limits to prevent runaway execution. The customized engine enforces:

• Maximum execution time to prevent infinite loops
• Memory consumption caps to protect the host process
• Restricted standard library features to limit system access

These sandboxing measures ensure that .ragsh scripts operate within safe boundaries while still retaining access to OpenHuman-specific capabilities.

Built-in OpenHuman Functions

The bridge between Rhai scripts and the OpenHuman core resides in src/openhuman/flows/rhai/functions.rs. This module registers custom functions that expose internal APIs to the scripting environment:

• run_tool(name, args) – Dispatches calls to the agent tool system
• http_get(url) – Performs authenticated HTTP requests through the core client
• memory_get(key) and memory_put(key, value) – Interact with the workspace memory store
• log(message) – Writes to the centralized tracing system

The registration process wraps Rust closures around core services, allowing Rhai scripts to invoke sophisticated operations with simple function calls.

Executing .ragsh Scripts

Execution binds the compiled AST to a runtime context that carries execution state and security credentials.

Runtime Context and Tool Dispatch

When the engine executes a script, it provides a runtime context containing the current thread ID, workspace path, and authentication tier. During execution, calls like run_tool("search", {...}) route through the registered function in src/openhuman/flows/rhai/functions.rs, which delegates to the tool dispatcher implemented in src/openhuman/tools/ops.rs.

This dispatcher maps the tool name to the appropriate agent implementation, executes the operation, and returns the result back into the Rhai environment as a native Dynamic value.

Result Handling and Persistence

.ragsh workflows return values—typically JSON objects—that the workflow runner interprets as the pipeline output. The engine captures this return value and persists it for downstream consumption, enabling complex multi-step automations where one workflow’s output feeds into subsequent processing stages.

Practical .ragsh Workflow Example

A typical .ragsh script combines multiple OpenHuman services. The following example from samples/flows/example.ragsh demonstrates fetching a web page, storing it in memory, and processing it through an agent tool:

// example.ragsh
// Fetch a web page, then store it in memory, then run a tool on the content.

let page = http_get("https://example.com");
memory_put("page_html", page);

let result = run_tool("summarize", {
    input: page,
    max_sentences: 3
});

log("Summarization result:", result);
result   // The value returned by the workflow

The Rust side initializes this execution through the RhaiEngine struct:

use openhuman::flows::rhai::engine::RhaiEngine;
use openhuman::flows::RagshRunner;

// Load the .ragsh file
let script = std::fs::read_to_string("workspace/flows/example.ragsh")?;

// Build a Rhai engine with OpenHuman functions
let rhai = RhaiEngine::new()?;

// Execute and get the result
let result = rhai.run(&script, &RagshRunner::new(thread_id))?;
println!("Workflow finished: {:?}", result);

Summary

• Lazy loading: .ragsh files live in the workspace flows/ directory and load through src/openhuman/flows/mod.rs
• Sandboxed execution: The custom Rhai engine in src/openhuman/flows/rhai/engine.rs applies time and memory limits for safe in-process execution
• Native API access: src/openhuman/flows/rhai/functions.rs registers bridge functions like run_tool(), http_get(), and memory_put() that connect scripts to core services
• Tool integration: Script calls route through src/openhuman/tools/ops.rs, enabling .ragsh workflows to invoke the same agent tools available to native Rust code
• Low latency: Because the Rhai engine runs in-process, workflows avoid IPC overhead and participate directly in OpenHuman’s approval gates and logging infrastructure

Frequently Asked Questions

What exactly is a .ragsh file?

A .ragsh file is a text file containing Rhai scripting language code that defines an OpenHuman workflow. It uses standard Rhai syntax plus OpenHuman-specific functions to automate tasks, process data, and orchestrate agent tools. These files reside in the flows/ directory of an OpenHuman workspace and execute within the embedded Rhai engine.

How does the Rhai engine maintain security during execution?

The engine construction code in src/openhuman/flows/rhai/engine.rs configures strict sandboxing parameters including maximum execution time, memory caps, and restricted access to system-level Rhai standard library features. Additionally, all I/O operations (HTTP requests, tool execution) route through audited Rust wrappers rather than direct system calls.

Can .ragsh workflows access external HTTP APIs?

Yes. The http_get() function registered in src/openhuman/flows/rhai/functions.rs exposes OpenHuman’s internal HTTP client to Rhai scripts. This client handles authentication headers, proxy configuration, and connection pooling automatically, allowing workflows to fetch external data safely without exposing raw network sockets to the scripting environment.

How do OpenHuman tools integrate with Rhai scripts?

When a script calls run_tool(), the registered function in src/openhuman/flows/rhai/functions.rs converts the Rhai arguments and invokes the central dispatcher in src/openhuman/tools/ops.rs. This dispatcher looks up the requested tool by name, validates permissions against the current authentication tier, executes the tool, and returns the result back to the Rhai runtime as a Dynamic value.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}