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

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

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 (lines 16-34).

---

Automated Setup: One-Command Installer

The recommended approach uses the official installer script at 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:

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

Launch the dev UI automatically after install:

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) (lines 94-104):

# 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 and installs Vite, Electron, and UI-specific tooling.

---

Understanding the Core npm Scripts

holaOS uses npm workspaces configured in the root 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
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

---

Optional Runtime Validation

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

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:

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) overrides the default ~/holaboss-ai path.

Build runtime for a specific platform vs. local source:

# 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 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 (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 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 (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.

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