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

> Set up your holaOS development environment quickly. Follow our complete install guide to install git, Node 24+, clone the repository, and bootstrap your entire holaOS development environment in minutes.

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

---

**Run `curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/main/scripts/install.sh | bash` to automatically install git, Node 24+, clone the repository, and bootstrap the entire holaOS development environment.**

The **holaOS** development environment requires Node 24+, git, and several workspace-specific dependencies across its Electron desktop app, runtime harnesses, and shared packages. This guide covers both the automated installer and manual setup steps, referencing actual source paths from the [holaboss-ai/holaOS](https://github.com/holaboss-ai/holaOS) repository.

---

## Prerequisites for holaOS Development

Before installing, verify your system meets these requirements:

- **Operating system**: macOS, Linux, or Windows Subsystem for Linux (WSL)
- **Command-line tools**: `curl`, `bash`, `git`
- **Node.js**: Version 24 or higher

Check your current versions:

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

npm --version

```

If Node is older than 24, the installer will automatically download a managed Node 24 build via the `install_managed_node` function in [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) (lines 16-34).

---

## Automated Setup: One-Command Installer

The recommended approach uses the official installer script at [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh). This script performs eight deterministic steps:

1. **Detects OS** (`detect_os`, lines 86-98)
2. **Installs git** if missing (`ensure_git`, lines 15-33)
3. **Ensures Node 24+** (`ensure_node_and_npm`, lines 16-34)
4. **Clones the repository** to `~/holaboss-ai` or custom path (`prepare_checkout`, lines 37-63)
5. **Installs desktop dependencies** (`npm run desktop:install`, line 68)
6. **Creates `.env` file** from template (`bootstrap_repo`, lines 71-75)
7. **Builds local runtime bundle** (`npm run desktop:prepare-runtime:local`, line 78)
8. **Verifies TypeScript build** (`npm run desktop:typecheck`, line 81)

Run the installer:

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

```

Launch the dev UI automatically after install:

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

```

---

## Manual Setup: Step-by-Step Commands

For explicit control over each step, follow the minimal command sequence from [[`INSTALL.md`](https://github.com/holaboss-ai/holaOS/blob/main/INSTALL.md)](https://github.com/holaboss-ai/holaOS/blob/main/INSTALL.md) (lines 94-104):

```bash

# 1. Clone the repository

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

# 2. Install desktop dependencies

npm run desktop:install

# 3. Create environment configuration

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

# 4. Build local runtime bundle

npm run desktop:prepare-runtime:local

# 5. Verify TypeScript compilation

npm run desktop:typecheck

# 6. Start development server

npm run desktop:dev

```

The `desktop:install` script is defined in [`apps/desktop/package.json`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/package.json) and installs Vite, Electron, and UI-specific tooling.

---

## Understanding the Core npm Scripts

holaOS uses **npm workspaces** configured in the root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json). These are the essential commands for holaOS development:

| Script | Purpose | Source Location |
|--------|---------|-----------------|
| `desktop:install` | Runs `npm ci` in `apps/desktop/`, installs Vite and Electron | [`apps/desktop/package.json`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/package.json) |
| `desktop:prepare-runtime:local` | Compiles runtime harnesses to `apps/desktop/out/runtime-<platform>` | `scripts/desktop-dev-isolated.mjs` |
| `desktop:prepare-runtime` | Downloads latest published runtime bundle | `scripts/desktop-dev-isolated.mjs` |
| `desktop:typecheck` | Full TypeScript type-check across monorepo | `scripts/desktop-dev-isolated.mjs` |
| `desktop:dev` | Starts Vite dev server with Electron main process watcher | [`apps/desktop/package.json`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/package.json) |

---

## Optional Runtime Validation

To verify the low-level harnesses that execute agents in isolated sandboxes:

```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 agent execution environment defined in the `runtime` package workspaces.

---

## Common Installation Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| System Node still used after install | PATH priority | Ensure `~/.local/bin` precedes system Node in PATH, or restart shell |
| "Unsupported Linux package manager" | Missing git | Install git manually (`sudo apt-get install git`), then re-run installer |
| Electron window fails to open | Headless environment | Stop after `desktop:typecheck`; installation is successful per `INSTALL.md:89-92` |
| Accidental secret commit | Modified `.env` file | Use `.env.example` values for local development only; never commit real credentials |

---

## Advanced: Custom Install Options

Install to a specific directory with auto-launch:

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

```

The `--dir` flag (lines 71-75 in [`install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/install.sh)) overrides the default `~/holaboss-ai` path.

Build runtime for a specific platform vs. local source:

```bash

# Use published runtime (faster, lines 79-85)

npm run desktop:prepare-runtime

# Build from source (needed for runtime modifications, line 78)

npm run desktop:prepare-runtime:local

```

Output appears in `apps/desktop/out/runtime-<platform>` and is auto-loaded by the Electron app.

---

## Summary

- **Fastest path**: Run the `curl | bash` installer for fully automated holaOS setup
- **Core requirement**: Node 24+ (installer provides managed version if needed)
- **Manual alternative**: Six explicit commands from `git clone` through `npm run desktop:dev`
- **Workspace structure**: Desktop app in `apps/desktop/`, shared packages in `packages/`, runtime harnesses in `runtime/`
- **Entry point**: The [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) orchestrates OS detection, dependency installation, and build verification

---

## Frequently Asked Questions

### What Node version does holaOS require?

**holaOS requires Node 24 or higher.** The installer automatically downloads a managed Node 24 build if your system version is older via the `install_managed_node` function in [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) (lines 16-34). You can verify your version with `node --version` before starting.

### Can I run holaOS on Windows without WSL?

**No—Windows development requires WSL.** The [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) installer and runtime harnesses are designed for macOS and Linux environments. Windows users should use Windows Subsystem for Linux (WSL2) as documented in the repository's installation prerequisites.

### What is the difference between `desktop:prepare-runtime` and `desktop:prepare-runtime:local`?

**`desktop:prepare-runtime` downloads the latest published runtime bundle** from holaOS releases, while **`desktop:prepare-runtime:local` compiles the runtime from source** in `runtime/harnesses/`. Use the local build when modifying the runtime harnesses; use the published version for faster setup or when only working on the desktop UI.

### Where does the installer clone the repository?

**By default, to `~/holaboss-ai`.** The `prepare_checkout` function in [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) (lines 37-63) creates this directory unless overridden with the `--dir` flag. The installer also supports `--launch` to immediately start `npm run desktop:dev` after completion.