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

> Easily set up your holaOS development environment. Run the automated installer script for Node 24+ and dependencies in one command. Get started with holaOS today.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: how-to-guide
- Published: 2026-08-15

---

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

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

npm --version

```

## One-Command Automated Installation

The repository provides a deterministic bootstrap script at [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/INSTALL.md).

The installer executes the following sequence defined in [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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:

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

```

To launch the development UI immediately after installation:

```bash
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`](https://github.com/holaboss-ai/holaOS/blob/main/INSTALL.md) (lines 94-104).

First, clone the repository and navigate to the directory:

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

```

Install the desktop application dependencies:

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

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

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

```bash
npm run desktop:typecheck

```

Finally, launch the development server:

```bash
npm run desktop:dev

```

## Understanding the Core Development Scripts

The monorepo uses **npm workspaces** defined in the root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) to hoist shared dependencies and orchestrate builds.

**[`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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:

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

```bash
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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) or manually executing the npm workspace commands.

- The **automated installer** at [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/INSTALL.md) documentation (lines 89-92), successful type-checking indicates a valid installation even if Electron cannot open a display window in headless environments.