OpenHuman Project Structure: How the Rust Core and React/Tauri Desktop Shell Work Together

The OpenHuman project uses a dual-layer architecture that isolates high-performance business logic in a Rust core from a modern React interface, packaging them together as a Tauri desktop application that communicates via an in-process HTTP-JSON-RPC bridge.

OpenHuman is an open-source AI agent platform designed as a dual-layer application. Understanding the OpenHuman project structure reveals how the repository cleanly separates the performance-critical Rust business logic from the React-based user interface while maintaining tight integration through a low-latency RPC mechanism.

Repository Layout: Core vs. Shell

The repository is deliberately partitioned into distinct directories. This separation ensures the core can function as a standalone binary or library while the desktop shell provides a native user experience.

The Rust Core (src/)

The src/ directory at the repository root implements all domain logic including agent behavior, memory management, tools, and security features. It provides JSON-RPC and CLI interfaces for external interaction.

• Primary Entry Point: src/main.rs builds the openhuman-core binary.
• Build Command: cargo build --bin openhuman-core
• Key Components: Domain controllers, provider abstractions (OpenAI-compatible APIs), and the Harness interface defined in src/openhuman/harness.rs.

The React/Tauri Shell (app/)

The app/ directory contains the pnpm workspace openhuman-app, which bundles a Vite + React frontend with a Tauri host process.

• React Entry: app/src/main.tsx initializes the user interface.
• Tauri Host: app/src-tauri/src/main.rs manages the native window and core process lifecycle.
• RPC Client: app/src/services/coreRpcClient.ts exposes coreRpcClient for frontend-to-core communication.

Documentation (gitbooks/)

Architecture overviews and design diagrams reside in gitbooks/developing/architecture.md, providing high-level visualizations of the Rust-Tauri integration.

Core-Shell Communication Architecture

The two layers communicate through an in-process HTTP-JSON-RPC server rather than traditional inter-process communication. This approach eliminates network overhead and ensures deterministic, low-latency behavior.

The core launches as a Tokio task via core_process::CoreProcessHandle inside the Tauri host. It exposes an HTTP server on a dynamic local port (http://127.0.0.1:<port>/rpc) using the method run_server_embedded_with_ready(), which accepts a one-time bearer token via the rpc_token: Some(_) parameter.

The React frontend retrieves this token through the Tauri command core_rpc_token, then instantiates the coreRpcClient (backed by relay_http_rpc) to invoke core methods. Environment variables provide alternative access patterns: OPENHUMAN_CORE_TOKEN for CLI or Docker usage, and OPENHUMAN_CORE_REUSE_EXISTING=1 to allow external debuggers to attach to running core instances.

Development Workflow and Build Commands

Building the OpenHuman project requires coordinating Rust and Node.js toolchains. The root package.json defines pnpm scripts that orchestrate both layers.

Compile the core library and binary:

cargo build --manifest-path Cargo.toml --bin openhuman-core

Run the core in standalone CLI mode for debugging:

./target/debug/openhuman-core serve

Start the full desktop development environment (Vite dev server + Tauri host):

pnpm dev:app

Build a production desktop bundle respecting Cargo feature gates:

pnpm build

The Tauri shell respects the same Cargo feature gates as the core, ensuring compile-time domain gating (e.g., voice, web3) applies uniformly to both layers.

Extending the Architecture

Adding functionality requires coordinated changes across both layers.

Adding a Domain to the Rust Core

New domains follow a modular pattern under src/openhuman/. After implementing schemas and controllers in a new directory (e.g., src/openhuman/example_domain/), register them in src/core/all.rs:

DomainGroup::Example => {
    all_example_controller_schemas(),
    all_example_controllers(),
}

Reference the domain's README.md at src/openhuman/example_domain/README.md for specific implementation guidelines.

Exposing a New UI Route

Frontend routes are defined in app/src/AppRoutes.tsx using standard React Router syntax:

<Route path="/example" element={<ExamplePage />} />

Code Examples

Initializing the Core from Rust

The Harness builder pattern in src/openhuman/harness.rs provides the primary interface for embedding the core:

use openhuman_core::Harness;

let harness = Harness::builder()
    .provider(openhuman_core::provider::Provider::openai_compatible(
        "https://api.openai.com/v1", "sk-…"
    ))
    .workspace(openhuman_core::Workspace::Ephemeral)
    .access(openhuman_core::Access::full())
    .backend_url("https://api.tinyhumans.ai")
    .build()
    .await?;

let result = harness.run("Summarize the repository structure.").await?;
println!("{}", result);

Invoking Core Methods from React

The frontend uses coreRpcClient from app/src/services/coreRpcClient.ts to communicate with the embedded core:

import { coreRpcClient } from '@/services/coreRpcClient';

async function askCore(prompt: string) {
  const response = await coreRpcClient.call('openhuman.agent_turn', {
    prompt,
    session_id: '',
  });
  return response.output;
}

Key Configuration Files

Several files define the integration boundaries between layers:

• Cargo.toml – Defines the core crate, dependencies, and feature gates (e.g., voice, web3) that propagate to the Tauri build.
• src/main.rs – Builds the openhuman-core binary and registers all domain controllers.
• app/package.json – Configures the pnpm workspace and defines npm scripts (dev, dev:app, build).
• app/src-tauri/src/main.rs – Implements the Tauri host, creates the in-process core task, and registers Tauri commands including core_rpc_token.
• gitbooks/developing/architecture.md – Contains the high-level architecture diagram describing the Rust-Tauri integration.

Summary

• The Rust core in src/ provides the business logic engine as a library and standalone binary, accessible via JSON-RPC.
• The React/Tauri shell in app/ packages the UI as a native desktop application using Vite for the frontend and Tauri for the host process.
• Communication occurs through an in-process HTTP-JSON-RPC bridge (relay_http_rpc) using a bearer token passed via run_server_embedded_with_ready().
• Development requires both cargo for the Rust layer and pnpm for the Node.js/Tauri layer, with feature gates synchronized across both.
• The architecture supports standalone core execution (cargo run --bin openhuman-core) for server-side or testing scenarios independent of the desktop UI.

Frequently Asked Questions

How does the React frontend communicate with the Rust core?

The React frontend communicates through an in-process HTTP-JSON-RPC server. The Tauri host starts the core as a Tokio task (core_process::CoreProcessHandle) which exposes http://127.0.0.1:<port>/rpc. The React application retrieves a bearer token via the Tauri command core_rpc_token, then uses coreRpcClient to invoke methods. This design eliminates network transport latency while maintaining language isolation.

Can the Rust core run independently of the Tauri desktop application?

Yes. The core can be compiled and executed as a standalone binary using cargo run --bin openhuman-core or started in server mode with ./target/debug/openhuman-core serve. This standalone mode supports CLI usage, Docker containers, and external debugging via the OPENHUMAN_CORE_REUSE_EXISTING=1 environment variable.

What development commands are needed to build both layers?

Use cargo build --bin openhuman-core to compile the Rust layer. For the desktop shell, use pnpm dev:app to start the development server or pnpm build to create production bundles. The root package.json orchestrates these commands, and the Tauri build process respects Cargo feature flags defined in Cargo.toml.

How do I add new functionality to both the core and UI?

To extend the system, create a new domain module under src/openhuman/ with schemas and controllers, then register it in src/core/all.rs. For the UI, add routes in app/src/AppRoutes.tsx and implement corresponding React components. Both changes respect the same feature gates, ensuring consistent availability of functionality across the core-shell boundary.

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