holaOS System Requirements: Complete Guide for macOS, Linux, and Windows WSL

holaOS runs on macOS (Apple Silicon or Intel), Linux, or Windows via WSL, requiring only curl, bash, git, and Node.js ≥24—all automatically verified and installed by the deterministic installer.

holaOS is a local-first, Electron-based desktop application designed for AI agent workflows. Whether you're deploying on a MacBook Pro, Ubuntu workstation, or Windows machine with WSL, understanding the holaOS system requirements ensures a smooth installation. The repository includes an automated installer in scripts/install.sh that detects your platform and provisions missing dependencies.

Supported Operating Systems

holaOS officially supports three platforms, with OS detection handled at runtime.

macOS

• Apple Silicon (M1/M2/M3) and Intel x86_64 architectures
• Automatic Homebrew integration for missing packages

Linux

• Major distributions with standard package managers (apt, yum, etc.)
• Native bash environment without additional emulation layers

Windows via WSL

• Windows Subsystem for Linux required—holaOS does not run natively on Windows
• Full Linux compatibility through WSL2 recommended

The detect_os function in scripts/install.sh:86-98 identifies your platform automatically:

# Excerpt from scripts/install.sh showing OS detection logic

detect_os() {
    case "$(uname -s)" in
        Linux*)     OS=Linux;;
        Darwin*)    OS=macOS;;
        CYGWIN*|MINGW*) OS=Windows;;
    esac
}

Required Command-Line Tools

Three core tools must be available to execute the one-line installer. The installer verifies each before proceeding.

Tool	Purpose	Auto-Installation
curl	Downloads the installer and dependencies	No—must be pre-installed
bash	Executes the installer script	No—must be pre-installed
git	Clones the repository and manages versions	Yes—via Homebrew (macOS) or system package manager (Linux)

Per INSTALL.md:54-61, verify these tools before running the installer:

curl --version   # must be present

bash --version   # must be present

git --version    # preferred, or installer will install it

Node.js and npm Requirements

Node.js version 24 or higher is mandatory. The holaOS repository bundles a managed Node 24.14.1 installation that supersedes your system version if outdated.

Managed Node Runtime

• Located in the repository's toolchain directory
• Automatically downloaded when system Node < 24
• Includes matching npm version

The installer logic in scripts/install.sh:20-28 handles version checking:

# Check system Node version vs. required minimum

if ! command -v node &> /dev/null || [[ "$(node -v | cut -d'v' -f2 | cut -d'.' -f1)" -lt 24 ]]; then
    echo "Installing managed Node 24.14.1..."
    install_managed_node
fi

Verify your current Node status:

node --version  # must output v24.x.x or higher

npm --version   # must be present alongside Node

Hardware and Runtime Environment

No explicit CPU or RAM thresholds are documented in the repository. However, as an Electron-based application, holaOS requires:

• Typical development machine capabilities
• Sufficient resources to host a Chromium renderer process
• ~2-4 GB available memory for build operations

The desktop application depends on a staged runtime bundle located at apps/desktop/out/runtime-<platform>. The installer prepares this automatically via npm run desktop:prepare-runtime:local (INSTALL.md:78-84).

Automated Installation (Recommended)

The deterministic one-line installer handles all requirement checks and dependency installation:

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

This command:

1. Detects your operating system (detect_os)
2. Verifies or installs git, curl, and bash
3. Checks Node.js version and installs managed Node 24 if needed
4. Clones the repository and prepares the runtime bundle
5. Launches the application with --launch flag

Manual Installation Steps

For environments where automated installers are restricted, follow the sequence documented in INSTALL.md:

# 1. Clone the repository

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

# 2. Install desktop dependencies

npm run desktop:install

# 3. Configure environment variables

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

# 4. Stage platform-specific runtime bundle

npm run desktop:prepare-runtime:local

# 5. Verify build integrity

npm run desktop:typecheck

# 6. Launch development instance (optional)

npm run desktop:dev

The .env.example file in apps/desktop/ provides required environment defaults; the installer copies this automatically if .env is missing.

Key Configuration Files

Understanding these files helps troubleshoot installation issues:

• INSTALL.md — Central documentation for minimum requirements and full installation procedures
• scripts/install.sh — Automated installer with detect_os, version checking, and managed Node provisioning
• apps/desktop/package.json — Declares Electron dependencies and npm scripts including desktop:install and desktop:prepare-runtime:local
• apps/desktop/.env.example — Template for runtime configuration variables

Summary

• holaOS system requirements are minimal: macOS, Linux, or Windows WSL with curl, bash, and internet access
• The scripts/install.sh installer automatically provisions git, Node.js 24+, and npm if absent
• No explicit hardware requirements—standard development machines suffice for Electron execution
• Manual installation requires cloning, dependency installation, environment configuration, and runtime bundle preparation
• All platforms use the same core toolchain with platform-specific runtime bundles staged automatically

Frequently Asked Questions

Does holaOS run on native Windows without WSL?

No. According to the source code in scripts/install.sh:86-98, holaOS detects Windows environments but requires WSL for execution. The installer does not support native Windows installation paths.

What if my system has Node.js 18 or 20 installed?

The managed Node 24.14.1 runtime automatically supersedes older system versions. As implemented in scripts/install.sh:20-28, the installer checks your Node version and downloads the bundled runtime if your system falls below version 24.

Can I use holaOS on a machine without internet access?

Partially. The one-line installer requires curl and internet connectivity for initial download. However, once cloned, the repository can be transferred offline. You would need to manually satisfy Node.js 24+, npm, and prepare the runtime bundle without the automated installer's assistance.

Is Apple Silicon fully supported or only Intel Macs?

Both architectures are equally supported. The detect_os function handles macOS generically, and the Electron-based runtime in apps/desktop/out/runtime-darwin bundles universal binaries compatible with M1/M2/M3 and Intel processors.

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