Developer Installation Guide

December 21, 2025 · View on GitHub

This guide covers everything you need to install and configure iDO for development.

Note: If you just want to use iDO without developing, see the User Installation Guide instead.

Prerequisites

Required Software

ToolVersionPurpose
Node.js≥ 20.xFrontend build tooling
pnpm≥ 9.xPackage manager
Python≥ 3.14Backend runtime
uvLatestPython package manager
RustLatest stableTauri runtime

Platform-Specific Requirements

macOS

  • macOS 13 (Ventura) or later
  • Xcode Command Line Tools: xcode-select --install
  • Accessibility and Screen Recording permissions (granted at first run)

Windows

  • Windows 10 or later
  • Visual Studio Build Tools or Visual Studio with C++ development tools
  • PowerShell 5.1 or later

Linux

  • Ubuntu 20.04+ or equivalent
  • Build essentials: sudo apt install build-essential curl wget
  • X11 or Wayland for GUI

Step 1: Install Core Tools

Install Node.js and pnpm

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Install pnpm globally
npm install -g pnpm

Install Python and uv

# Install Python 3.14+ (using pyenv recommended)
curl https://pyenv.run | bash
pyenv install 3.14
pyenv global 3.14

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Install Rust

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

Step 2: Clone the Repository

git clone https://github.com/UbiquantAI/iDO.git
cd iDO

Windows-Specific: Configure Git Line Endings

On Windows, you must configure Git to prevent line ending issues:

git config core.autocrlf false

This ensures Git doesn't automatically convert line endings, which can cause issues when collaborating across platforms.

Step 3: Install Project Dependencies

# macOS/Linux
pnpm setup

# Windows
pnpm setup:win

This single command will:

  • ✅ Install all Node.js dependencies
  • ✅ Initialize Python virtual environment (.venv in project root)
  • ✅ Install Python dependencies
  • ✅ Validate i18n translations

Manual Installation

If you prefer to install dependencies step by step:

# 1. Install frontend dependencies
pnpm install

# 2. Initialize Python virtual environment
uv sync

# 3. Validate translations
pnpm check-i18n

Step 4: Verify Installation

Check All Tools

# Node.js and pnpm
node --version    # Should be ≥ 20.x
pnpm --version    # Should be ≥ 9.x

# Python and uv
python --version  # Should be ≥ 3.14
uv --version

# Rust
rustc --version
cargo --version

Test Frontend Build

pnpm dev
# Should start dev server at http://localhost:5173

Test Backend

# Option 1: Standalone FastAPI server
uvicorn app:app --reload
# Visit http://localhost:8000/docs

# Option 2: Full Tauri app
pnpm tauri dev

Troubleshooting

Python Virtual Environment Issues

Problem: uv sync fails or Python modules not found

Solution:

# Remove and recreate virtual environment
rm -rf .venv
uv sync

# Verify virtual environment
which python  # Should point to .venv/bin/python

Node Modules Issues

Problem: pnpm install fails or modules missing

Solution:

# Clean cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Rust Compilation Errors

Problem: Tauri fails to compile

Solution:

# Update Rust toolchain
rustup update stable

# Clean build artifacts
pnpm clean

# Rebuild
pnpm tauri build

Windows Line Ending Issues

Problem: Git shows many files modified but no actual changes

Solution:

# Configure git
git config core.autocrlf false

# Reset repository
git add .
git reset --hard HEAD

macOS Permission Issues

Problem: Application can't monitor keyboard/mouse

Solution: Grant Accessibility and Screen Recording permissions in System Settings > Privacy & Security. The app will prompt you when these permissions are needed.

Next Steps

Additional Resources