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

> Discover how the Rhai scripting engine powers OpenHuman's .ragsh workflow tools. Achieve low-latency automation by invoking agent tools, memory APIs, and HTTP clients directly.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-30

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/rhai/functions.rs), which delegates to the tool dispatcher implemented in [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```rhai
// 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:

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/mod.rs)
- **Sandboxed execution**: The custom Rhai engine in [`src/openhuman/flows/rhai/engine.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/rhai/functions.rs) converts the Rhai arguments and invokes the central dispatcher in [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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.