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

> Set up your OpenHuman development environment with ease. Follow our complete guide to install Node.js, pnpm, Rust, clone the repo, and launch the application quickly.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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.

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```bash
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:

```bash

# 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`](https://github.com/tinyhumansai/openhuman/blob/main/config.toml), with schema definitions in [`src/openhuman/config/schema/types.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```bash
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):**

```bash
pnpm test           # Run unit tests

pnpm test:coverage  # Generate coverage reports

```

**Rust Core Tests:**

```bash
pnpm test:rust      # Wrapper around cargo test

```

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

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

```

**End-to-End Desktop Tests:**

For Linux environments, use the Docker-based bootstrap:

```bash
./e2e/run-local.sh

```

Or manually launch the app and run WebdriverIO specs:

```bash
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`](https://github.com/tinyhumansai/openhuman/blob/main/config.toml):

```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`](https://github.com/tinyhumansai/openhuman/blob/main/./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.