How to Build OpenHuman from Source: Complete Development Setup

Building OpenHuman from source requires Node.js 24+, pnpm 10.10, Rust 1.93, and CMake; clone the repository with submodules, install dependencies with pnpm install, copy the environment templates, then run either the web UI (pnpm dev), desktop app (pnpm --filter openhuman-app dev:app), or standalone Rust core (cargo run --bin openhuman-core).

OpenHuman is a hybrid project maintained in the tinyhumansai/openhuman repository that combines a Rust core for business logic with a React and Tauri desktop shell. To build from source, you must coordinate a polyglot toolchain that compiles the Rust JSON-RPC server alongside the JavaScript frontend. This guide follows the official contribution workflow documented in CONTRIBUTING.md to ensure your development environment matches the upstream configuration.

Prerequisites

Before cloning, install the system-level compilers and tooling required by the Rust crates (including Whisper bindings) and the Tauri/CEF build:

• Node.js 24 or higher
• pnpm 10.10 (the package manager used for the monorepo workspace)
• Rust 1.93 (install via rustup)
• CMake and Ninja (for native C++ dependencies)
• ripgrep (for search utilities)

Platform-specific dependencies:

• macOS: brew install node@24 pnpm rustup-init cmake ninja ripgrep
• Linux: Install build-essential, libgtk-3-dev, libwebkit2gtk-4.0-dev, libayatana-appindicator3-dev, plus cmake, ninja, and ripgrep.
• Windows: Install Visual Studio C++ Build Tools, LLVM, and CMake, then Node.js 24 and pnpm.

Clone the Repository and Initialize Submodules

OpenHuman vendors a patched Tauri CLI and Chromium Embedded Framework (CEF) sources required for the desktop build. You must clone with submodules to populate app/src-tauri/vendor.

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

The app/src-tauri/vendor/tauri-cef directory contains the custom Chromium build that enables mascot video rendering and other native features.

Install Dependencies and Configure Environment

Install the workspace JavaScript dependencies and bootstrap the Rust environment:

pnpm install

Copy the environment templates to local files before running any build commands:

cp .env.example .env
cp app/.env.example app/.env.local

These files provide default configuration for the Rust core, Tauri shell, and frontend. No secrets are committed to the repository, but the application will fail to start without these local files.

Choose Your Build Mode

The repository supports three distinct development entry points depending on which layer you are modifying.

Web-Only Development Server

Run the Vite development server for rapid UI iteration without compiling the desktop shell:

pnpm dev

This starts the frontend at http://localhost:5173 and assumes the core is running separately or mocked.

Full Desktop Application

Build the complete Tauri application with the embedded Rust core and CEF renderer:

pnpm --filter openhuman-app dev:app

This command uses the vendored Tauri CLI in app/src-tauri/vendor to ensure the correct CEF environment is initialized. It bundles the openhuman-core binary as an embedded child process and provides native OS integrations like notifications and deep linking.

Standalone Rust Core

Run only the Rust JSON-RPC server for backend development or API integration:

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

The core prints its RPC endpoint (e.g., http://127.0.0.1:7788/rpc) and can run independently of the frontend. In the full desktop build, UI-to-core communication flows through invoke('core_rpc_relay', …) calls bridged by the Tauri shell.

Verify Your Build

Ensure the environment is correctly configured by running the linting and type-checking suites:

pnpm typecheck      # TypeScript compilation

pnpm lint           # ESLint

pnpm format:check   # Prettier + rustfmt

cargo check         # Rust compilation

All checks should complete without errors. Optionally, run the full test matrix:

pnpm test        # Frontend unit tests

pnpm test:rust   # Rust tests

pnpm test:e2e    # Desktop end-to-end tests

Summary

• Prerequisites: Node 24+, pnpm 10.10, Rust 1.93, CMake, and Ninja are required to compile the Rust core and Tauri shell.
• Submodules: The app/src-tauri/vendor directory contains vendored Tauri CEF sources that must be fetched with git submodule update --init --recursive.
• Environment: Copy .env.example to .env and app/.env.example to app/.env.local before starting any build.
• Entry Points: Use pnpm dev for web-only, pnpm --filter openhuman-app dev:app for the full desktop app, or cargo run --bin openhuman-core for the standalone Rust server.
• Quality Gates: Run pnpm typecheck, pnpm lint, and cargo check to verify the build health.

Frequently Asked Questions

Why do I need to clone with submodules?

The app/src-tauri/vendor directory contains a patched Tauri CLI and Chromium Embedded Framework (CEF) sources required for the desktop application's native video rendering and OS integrations. Without these submodules, the pnpm --filter openhuman-app dev:app command will fail to locate the custom Chromium build.

What is the difference between the web-only and desktop builds?

The web-only build (pnpm dev) runs the React frontend through the Vite development server for rapid UI prototyping. The desktop build (pnpm --filter openhuman-app dev:app) compiles the Tauri shell and embeds the Rust core as a child process, providing native OS features and the custom CEF renderer required for full functionality.

Can I run the Rust core without installing Node.js?

Yes. If you only need the JSON-RPC server, you can build and run the core using only Rust tooling: cargo run --bin openhuman-core. This is useful for backend development or headless deployments. However, building the full desktop application requires Node.js and pnpm to compile the frontend and manage the Tauri build process.

Where are the Rust core and Tauri shell defined?

The Rust core binary (openhuman-core) is declared in src/Cargo.toml at the repository root. The Tauri desktop shell, which links the embedded core and provides the native window, is defined in app/src-tauri/Cargo.toml. The React frontend entry point resides in app/src/.

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