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

The fastest way to set up a holaOS development environment is to run the automated installer script, which handles Node 24+, dependency installation, and runtime preparation in a single command.

holaOS is an open-source, multi-package workspace that powers an Electron-based desktop UI and isolated runtime harnesses for AI agents. Setting up a development environment requires Node 24 or higher, git, and several build dependencies. Whether you prefer a one-command automated approach or manual step-by-step configuration, this guide covers both methods using the exact implementation details from the holaboss-ai/holaOS repository.

Prerequisites

Before installing holaOS, verify your system meets the baseline requirements. The codebase requires Node.js version 24 or higher, which the installer can manage automatically if your system version is outdated. You also need git, curl, and bash available in your PATH.

Supported operating systems include macOS, Linux, and Windows Subsystem for Linux (WSL). While Homebrew simplifies macOS dependency management, standard Linux package managers (apt, dnf, pacman) work for other platforms.

Verify your current versions:

git --version
node --version   # must be >= 24

npm --version

One-Command Automated Installation

The repository provides a deterministic bootstrap script at scripts/install.sh that automates the entire setup process. This script handles OS detection, dependency installation, repository cloning, and initial build verification according to the deterministic runbook in INSTALL.md.

The installer executes the following sequence defined in scripts/install.sh:

• detect_os (lines 86-98): Identifies macOS or Linux variant and sets package manager variables
• ensure_git (lines 15-33): Installs git via the system package manager if missing
• ensure_node_and_npm (lines 16-34): Downloads managed Node 24 to ~/.local/bin if system version is insufficient
• prepare_checkout (lines 37-63): Clones into ~/holaboss-ai or a custom directory you specify
• npm run desktop:install: Installs Electron and Vite tooling via the workspace definition in apps/desktop/package.json
• bootstrap_repo (lines 71-75): Creates apps/desktop/.env from the example template at apps/desktop/.env.example
• npm run desktop:prepare-runtime:local (line 78): Builds the local runtime bundle for the desktop app
• npm run desktop:typecheck (line 81): Validates TypeScript compilation across the monorepo

Execute the automated installation:

curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/main/scripts/install.sh | bash

To launch the development UI immediately after installation:

curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/main/scripts/install.sh | bash -s -- --launch

Manual Setup Process

If you prefer explicit control over each step or already have the repository cloned, follow the minimal command sequence from INSTALL.md (lines 94-104).

First, clone the repository and navigate to the directory:

git clone https://github.com/holaboss-ai/holaOS.git holaboss-ai
cd holaboss-ai

Install the desktop application dependencies:

npm run desktop:install

This command executes npm ci within the apps/desktop/ workspace, installing Electron, Vite, and all UI-specific tooling.

Create the environment configuration file:

cp apps/desktop/.env.example apps/desktop/.env

The .env.example file contains template variables for API keys and runtime configuration. Copy this to apps/desktop/.env before starting the application.

Build the local runtime bundle:

npm run desktop:prepare-runtime:local

This command invokes scripts/desktop-dev-isolated.mjs to compile the low-level harnesses from runtime/harnesses/ into apps/desktop/out/runtime-<platform>.

Verify the TypeScript build integrity:

npm run desktop:typecheck

Finally, launch the development server:

npm run desktop:dev

Understanding the Core Development Scripts

The monorepo uses npm workspaces defined in the root package.json to hoist shared dependencies and orchestrate builds.

scripts/install.sh The primary bootstrap entry point that detects your OS, ensures system dependencies, and chains subsequent installation steps. Functions like detect_os and prepare_checkout handle platform-specific logic.

npm run desktop:install Defined in apps/desktop/package.json, this script installs Electron-specific dependencies including the Vite dev server and desktop build tools.

npm run desktop:prepare-runtime:local Packages the runtime harnesses into apps/desktop/out/runtime-<platform> for the UI to load. This differs from npm run desktop:prepare-runtime, which pulls the latest published runtime rather than building from local source.

npm run desktop:typecheck Performs a full TypeScript type-check across the monorepo using the orchestration logic in scripts/desktop-dev-isolated.mjs, ensuring type safety before runtime execution.

npm run desktop:dev Starts the Vite development server and Electron main process with hot reloading enabled.

Optional Runtime Validation

To verify the lower-level agent execution environment compiles and passes tests, run the runtime-specific build commands:

npm run runtime:state-store:install
npm run runtime:state-store:build
npm run runtime:harness-host:install
npm run runtime:harness-host:build
npm run runtime:api-server:install
npm run runtime:test

These commands exercise the isolated sandbox environment defined in the runtime package workspaces, ensuring the harnesses that execute AI agents function correctly outside the Electron context.

Troubleshooting Common Issues

Node Version Conflicts If you have Node < 24, the installer downloads a managed version to ~/.local/bin via the install_managed_node routine. Ensure this directory precedes your system Node in PATH, or restart your shell to refresh environment variables after the installer completes.

Missing Git on Linux The ensure_git function attempts automatic installation, but some minimal Linux distributions may require manual installation first:

sudo apt-get install git  # Debian/Ubuntu

sudo dnf install git      # Fedora

Headless Environment Failures If npm run desktop:dev crashes or hangs in CI/CD environments without display capabilities, this indicates Electron cannot initialize a window. According to INSTALL.md (lines 89-92), the installation remains valid if you abort after npm run desktop:typecheck completes successfully.

Environment Variable Security Never commit real secrets to apps/desktop/.env. The repository only tracks .env.example. Always verify your .env file appears in .gitignore before adding production API keys or credentials.

Summary

Setting up the holaOS development environment requires either running the automated scripts/install.sh or manually executing the npm workspace commands.

• The automated installer at scripts/install.sh handles Node 24+, git installation, repository cloning into ~/holaboss-ai, and dependency setup in one command
• Manual setup requires running npm run desktop:install, copying apps/desktop/.env.example to .env, and executing npm run desktop:prepare-runtime:local
• Key entry points include apps/desktop/package.json for scripts and scripts/desktop-dev-isolated.mjs for build orchestration
• The runtime harnesses in runtime/harnesses/ require separate build steps for full validation of the agent execution environment
• Always verify TypeScript compilation with npm run desktop:typecheck before launching npm run desktop:dev

Frequently Asked Questions

What Node.js version is required for holaOS development?

holaOS requires Node.js version 24 or higher. The ensure_node_and_npm function in scripts/install.sh automatically downloads a managed Node 24 build to ~/.local/bin if your system version is older, ensuring compatibility without interfering with existing Node installations.

Where does the installer clone the holaOS repository?

By default, scripts/install.sh clones the repository into ~/holaboss-ai. You can specify a custom directory using the --dir flag, such as curl -fsSL [installer-url] | bash -s -- --dir /opt/holaOS. The prepare_checkout function (lines 37-63) handles directory creation and git clone operations.

How do I fix PATH issues after the installer adds managed Node 24?

If commands still reference an older Node version after installation, ensure ~/.local/bin appears in your PATH environment variable before system directories like /usr/bin. Source your shell configuration or restart the terminal to apply changes made by the install_managed_node routine.

Can I build holaOS without launching the Electron UI?

Yes. Run through npm run desktop:typecheck and stop before npm run desktop:dev. According to the repository's INSTALL.md documentation (lines 89-92), successful type-checking indicates a valid installation even if Electron cannot open a display window in headless environments.

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