How to Set Up a Development Environment for OpenHuman: Complete Setup Guide

Install Node.js 24+, pnpm 10.10.0+, and Rust 1.93.0+, clone the repository with git submodule update --init --recursive, run pnpm install, and launch the full stack with pnpm dev:app to begin developing the hybrid Rust and React desktop application.

OpenHuman is a hybrid desktop application architecture combining a Rust core (JSON-RPC/CLI) with a React + Tauri v2 user interface. When you set up a development environment for OpenHuman, you are configuring a workspace that orchestrates both the high-performance Rust backend and the modern TypeScript frontend through Tauri's CEF-enabled shell. This guide covers the exact toolchain versions, repository initialization steps, and development workflows used in the tinyhumansai/openhuman codebase.

Prerequisites and Toolchain Versions

OpenHuman requires specific minimum versions across multiple ecosystems. Ensure you have the following installed before proceeding:

• Git (any version) for cloning and submodule management
• Node.js 24+ for the React/Tauri frontend
• pnpm 10.10.0+ (the required package manager)
• Rust 1.93.0+ with rustfmt and clippy components for the core library
• CMake and Ninja for building native Rust dependencies
• ripgrep for repository linting tools
• Platform-specific build tools: Xcode on macOS, glibc development packages on Linux, or MSVC build tools on Windows

Running pnpm install automatically resolves Node-side dependencies, but the system-level toolchains must be present first.

Clone and Initialize the Repository

The repository contains a vendored Tauri/CEF submodule that must be initialized for the desktop shell to build correctly.

git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
git submodule update --init --recursive

The submodule step is non-negotiable—without the CEF-enabled Tauri CLI in the submodule, the desktop application cannot launch. After initialization, verify the workspace structure contains openhuman-app (React UI) and openhuman-app/src-tauri (Tauri host).

Install Frontend Dependencies

Install the workspace dependencies from the root directory:

pnpm install

This command populates the node_modules for the pnpm workspace, which includes the Vite-powered React UI in app/src/ and the Tauri configuration in app/src-tauri/. You can verify the workspace layout by running pnpm workspaces list.

Build and Run the Application

OpenHuman supports three distinct development modes depending on which layer you are testing.

Web-Only UI Development

For rapid UI iteration without the desktop shell overhead:

pnpm dev

This starts the Vite development server without launching Tauri, useful for testing React components in isolation.

Full Desktop Development

For end-to-end testing with the Rust core:

pnpm dev:app

This command launches the Tauri host, which automatically starts the Rust core in-process via the core_process module located in app/src-tauri/src/core_process.rs. The core_rpc_relay Tauri command in this file forwards RPC calls between the UI and the core.

Production Build

To generate a static bundle for deployment:

pnpm build

This outputs the production-ready UI bundle to app/dist/.

Develop the Rust Core Independently

The core library lives under src/ and can be developed separately from the UI. Navigate to the core for standalone work:

# Check the core without building

cargo check --manifest-path Cargo.toml

# Build the standalone CLI binary

cargo build --bin openhuman-core

# Run the JSON-RPC server directly

./target/debug/openhuman-core serve

The core reads configuration from config.toml, with schema definitions in src/openhuman/config/schema/types.rs. When running standalone, the core exposes JSON-RPC endpoints that the UI normally accesses through the Tauri bridge.

Code Quality and Testing

Linting, Formatting, and Type Checking

The repository enforces strict quality gates that mirror CI requirements:

pnpm lint           # ESLint with caching

pnpm format:check   # Prettier and cargo fmt --check

pnpm typecheck      # TypeScript compilation via tsc --noEmit

Running the Test Suite

OpenHuman maintains separate test suites for each architecture layer.

Frontend Unit Tests (Vitest):

pnpm test           # Run unit tests

pnpm test:coverage  # Generate coverage reports

Rust Core Tests:

pnpm test:rust      # Wrapper around cargo test

For targeted end-to-end JSON-RPC tests, use the provided mock script:

scripts/test-rust-with-mock.sh --test json_rpc_e2e

End-to-End Desktop Tests:

For Linux environments, use the Docker-based bootstrap:

./e2e/run-local.sh

Or manually launch the app and run WebdriverIO specs:

pnpm dev:app
pnpm debug e2e test/e2e/specs/smoke.spec.ts

Optional: Configure Local AI (Ollama)

To route inference requests to a local Ollama instance instead of the managed backend, modify config.toml:

[model_routing]
use_local = true
local_endpoint = "http://localhost:11434"

The core will then direct AI queries to your local Ollama server at the specified endpoint.

Summary

• Install prerequisites: Node.js 24+, pnpm 10.10.0+, Rust 1.93.0+, CMake, Ninja, and ripgrep.
• Clone with submodules: Use git submodule update --init --recursive to fetch the Tauri/CEF components required for the desktop shell.
• Use pnpm scripts: pnpm dev for UI-only work, pnpm dev:app for full-stack development, and pnpm build for production bundles.
• Develop core independently: Run cargo build --bin openhuman-core and ./target/debug/openhuman-core serve to test the JSON-RPC server standalone.
• Maintain quality: Run pnpm lint, pnpm format:check, and pnpm typecheck before submitting changes to match CI requirements.
• Test thoroughly: Execute pnpm test for Vitest, pnpm test:rust for cargo tests, and use ./e2e/run-local.sh for Docker-based E2E validation.

Frequently Asked Questions

Do I need to install Tauri separately to develop OpenHuman?

No. OpenHuman vendors its Tauri/CEF CLI through a Git submodule. As long as you run git submodule update --init --recursive after cloning, the required Tauri components are available locally. You only need the system-level platform dependencies (like Xcode on macOS or build-essential on Linux) that Tauri requires to compile native code.

Can I develop the React UI without running the Rust core?

Yes. Run pnpm dev to start the Vite development server in web-only mode. This launches the React frontend without the Tauri desktop shell or Rust core process, allowing rapid iteration on UI components. However, features requiring the JSON-RPC bridge (like core data operations) will not function until you run pnpm dev:app.

How do I run tests for only the Rust core without the frontend?

Use the pnpm test:rust command, which wraps cargo test, or invoke Cargo directly with cargo test --manifest-path Cargo.toml. For specific integration tests against the JSON-RPC interface, use scripts/test-rust-with-mock.sh --test json_rpc_e2e to execute tests against a mock backend.

What should I do if the CEF submodule fails to initialize?

Ensure you cloned the repository with the --recursive flag or ran git submodule update --init --recursive afterwards. If the submodule directory remains empty, check your Git configuration for HTTPS access to the submodule URL. The CEF-enabled Tauri CLI is essential for building the desktop application; without it, pnpm dev:app will fail to locate the Tauri executable.

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