Skip to main content

Getting Set Up

This guide covers the full desktop/source install path and release installers.

Prerequisites​

  • git
  • Node.js 24 or newer (see app/package.json)
  • pnpm@10.10.0 (see root package.json packageManager field)
  • Rust 1.93.0 via rustup, with rustfmt and clippy (see rust-toolchain.toml)
  • CMake, for native Rust dependencies
  • Git submodules under app/src-tauri/vendor/, for vendored CEF-aware Tauri CLI
  • Platform desktop build tools: Xcode Command Line Tools on macOS, or Tauri GTK/WebKit/AppIndicator package set on Linux

macOS Homebrew Quick Start​

brew install node@24 pnpm rustup-init cmake
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

Arch Linux Quick Start​

sudo pacman -S --needed nodejs npm rustup cmake base-devel clang openssl \
  alsa-lib xdotool libxtst libxi libevdev gtk3 webkit2gtk-4.1 \
  libayatana-appindicator librsvg patchelf nss nspr at-spi2-core \
  libcups libdrm libxkbcommon libxcomposite libxdamage libxfixes \
  libxrandr mesa pango cairo libxshmfence
npm install -g pnpm@10.10.0
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

Build from Source (Local Compilation)​

From the repo root:

# 1) Clone and enter repo
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2) Get vendored Tauri/CEF sources
git submodule update --init --recursive

# 3) Install JS dependencies (workspace)
pnpm install

# 4) Build desktop app artifacts
pnpm build

For local development:

# Web UI only development
pnpm dev

# Desktop app development (using vendored Tauri/CEF CLI)
pnpm --filter openhuman-app dev:app

Install Latest Stable Release (macOS/Linux x64)​

Main install command:

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

Arch Linux Package​

The repo at packages/arch/openhuman-bin contains the openhuman-bin AUR recipe.

Windows (Latest Stable)​

Using PowerShell:

irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

ARM Linux Build (aarch64)​

ARM Linux builds require special handling.

Prerequisites​

sudo apt install xvfb

Build​

cd app
pnpm tauri build --target aarch64-unknown-linux-gnu

Running​

The binary needs the CEF library path set:

REL_DIR=app/src-tauri/target/aarch64-unknown-linux-gnu/release
CEF_DIR=$(ls -d "$REL_DIR"/build/cef-dll-sys-*/out/cef_linux_aarch64 2>/dev/null | head -n1)
export LD_LIBRARY_PATH="$CEF_DIR:$REL_DIR/deps:$REL_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
"$REL_DIR/OpenHuman" --no-sandbox

Troubleshooting​

macOS: pnpm dev:app exits with "CEF cache is held by another OpenHuman instance"​

Symptom

pnpm dev:app exits before a window appears, with a message like:

[openhuman] CEF cache at /Users/<you>/Library/Caches/com.openhuman.app/cef is held by another OpenHuman instance

Cause

CEF holds an exclusive lock on its user data directory via a SingletonLock symlink. The installed .app bundle and the dev binary use the same identifier (com.openhuman.app), so they cannot run in parallel.

Fix

Kill other OpenHuman instances and rerun:

pkill -f "OpenHuman.app/Contents"
pkill -f "openhuman-core"
pnpm dev:app

Stale openhuman RPC process holding the core port​

Symptom

A previous Tauri build or openhuman-core run left a process listening on OPENHUMAN_CORE_PORT (default 7788).

Current Behavior

core_process::ensure_running probes the port on startup:

  • If the listener is identified as an OpenHuman core, it's treated as stale and terminated
  • If the listener is something else (or not HTTP), startup fails loudly

Next Steps​