What Dependencies Are Required to Run HolaOS? Complete Installation Guide

HolaOS requires three layers of dependencies: root-level tooling (Turbo and Bun), workspace packages across apps/* and packages/* directories, and desktop-specific libraries including Electron, React, and native modules like SQLite and Sharp. This monorepo structure means you'll install everything through a single wrapper script rather than managing dependencies manually.

HolaOS is a monorepo developed by holaboss-ai that bundles desktop applications, runtime services, and SDKs into a unified system. Understanding its dependency layers is essential for successful local development and production builds. This guide breaks down exactly what you need to install and where each dependency is declared in the source code.

Root-Level Tooling Dependencies

The foundation of HolaOS relies on modern JavaScript tooling declared in the root package.json.

Turbo Task Runner

Turbo serves as the monorepo task runner, orchestrating builds and scripts across all workspaces. The root package.json lists turbo as its sole devDependency at lines 58-70.

Bun Package Manager

Bun replaces npm as the primary package manager for faster installs and better monorepo handling. All installation commands in HolaOS wrap bun install rather than npm install.

Trusted Native Binaries

The root package.json contains a trustedDependencies array that automatically installs native binaries required for Electron builds. This includes:

• Electron (the desktop runtime)
• SQLite (via better-sqlite3)
• Sharp (image processing library)

These are declared in /cache/repos/github.com/holaboss-ai/holaOS/main/package.json#58-70 and install automatically when running the setup script.

Workspace Structure and Dependencies

HolaOS organizes code into distinct workspaces defined in the root package.json at lines 70-79.

Workspace Categories

Directory	Purpose
apps/*	Full applications (desktop, server)
packages/*	Shared libraries and SDKs
runtime/*	Execution environment components

Each workspace maintains its own package.json with specific dependencies for its role. The root workspaces field ensures Bun hoists and links dependencies correctly across the monorepo.

Desktop Application Dependencies

The Electron-based desktop app in apps/desktop/package.json carries the heaviest dependency load, spanning lines 62-124.

Electron Build Tools

{
  "@electron/rebuild": "^3.x",
  "electron": "^28.x",
  "electron-builder": "^24.x"
}

These handle native module compilation, runtime packaging, and installer generation.

Native Modules

• better-sqlite3 — Embedded SQLite database with direct Node.js bindings
• sharp — High-performance image processing for thumbnails and conversions

Both require platform-specific compilation, which @electron/rebuild handles automatically.

React UI Stack

The desktop interface builds on modern React patterns:

Library	Purpose
react / react-dom	Core UI framework
@tanstack/react-query	Server state management
@tiptap/*	Rich text editor components
@xyflow/react	Node-based visual workflows
tailwindcss	Utility-first CSS styling

HolaOS SDKs

The desktop app consumes internal packages published under the @holaboss scope:

• @holaboss/app-host — Application container runtime
• @holaboss/app-sdk — Core SDK for app development
• @holaboss/editor — Collaborative editing components
• @holaboss/remote-api — Remote procedure call layer
• @holaboss/runtime-client — Client-side runtime connector

Utility Libraries

Additional production dependencies include clsx (conditional classes), dotenv (environment loading), archiver (compression), exceljs (spreadsheet generation), jszip (ZIP handling), and qrcode (code generation).

Optional and Platform-Specific Dependencies

The desktop package.json declares conditional dependencies at lines 126-131.

macOS-Only Features

{
  "optionalDependencies": {
    "node-mac-permissions": "^2.x"
  }
}

This native module handles macOS permission dialogs for microphone, camera, and screen recording access. It installs only on Darwin platforms and fails silently on Windows/Linux.

Dependency Overrides

The overrides field pins specific versions of transitive dependencies like kysely (type-safe SQL query builder) to ensure compatibility across the monorepo.

Installing HolaOS Dependencies

Rather than installing each layer separately, use the provided wrapper script.

One-Command Installation

npm run desktop:install

This executes bun install scoped to the desktop workspace while automatically pulling root dependencies and trusted native binaries.

Complete Setup Workflow

# 1️⃣ Clone and enter repository

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

# 2️⃣ Install all Node/Bun dependencies (root + desktop)

npm run desktop:install

# 3️⃣ Build the Electron runtime bundle from local source

npm run desktop:prepare-runtime:local

# 4️⃣ Verify the TypeScript build passes

npm run desktop:typecheck

# 5️⃣ Launch the development environment

npm run desktop:dev

Each script chains prerequisite steps, eliminating manual dependency management.

Key Installation Files and Scripts

Understanding these files helps troubleshoot dependency issues.

File Path	Function
package.json (root)	Declares workspaces, Turbo configuration, and trusted native dependencies
apps/desktop/package.json	Complete inventory of UI libraries, SDKs, and Electron tools
scripts/install.sh	System prerequisite checker (git, Node 24+), environment file creation, and runtime preparation
apps/desktop/scripts/ensure-electron-install.mjs	Verifies Electron binaries and triggers trusted dependency installation when missing

The ensure-electron-install.mjs script specifically checks whether node_modules/electron/dist exists and re-runs the trust installation if binaries are corrupted or outdated.

System Requirements

Based on the source analysis, HolaOS requires:

• Node.js 24+ (enforced in scripts/install.sh)
• Git (for workspace cloning and submodule handling)
• Platform build tools (make, gcc, python3) for native module compilation
• macOS 12+ for full feature support (node-mac-permissions)

Windows and Linux run the core application but skip macOS-specific permission handling.

Summary

• Root dependencies: Turbo task runner, Bun package manager, and trusted native binaries (Electron, SQLite, Sharp) declared in root package.json lines 58-70
• Workspace system: Monorepo structure with apps/*, packages/*, and runtime/* directories configured at lines 70-79
• Desktop stack: Electron build tools, React UI libraries, HolaOS SDKs, and utility packages in apps/desktop/package.json lines 62-124
• Optional components: macOS permissions module and dependency overrides at lines 126-131
• Installation method: Single command npm run desktop:install handles all layers automatically
• Verification: Run npm run desktop:typecheck and npm run desktop:dev to confirm successful setup

Frequently Asked Questions

What package manager does HolaOS use?

HolaOS uses Bun as its primary package manager. While wrapper scripts accept npm commands, they execute bun install internally for faster, more reliable monorepo installations. The root package.json contains no npm-specific lockfile—Bun's bun.lockb handles dependency resolution instead.

Why does installation require trusted dependencies?

Native modules like Electron, SQLite, and Sharp contain platform-specific binaries that must compile against your local system libraries. The trustedDependencies array in root package.json authorizes these downloads automatically, bypassing the manual confirmation typically required for native code execution.

Can I run HolaOS without the desktop application?

No—the desktop Electron application is the primary entry point for HolaOS. While individual workspace packages in packages/* can be built and tested in isolation, the full system requires the desktop runtime to coordinate between the UI layer and background services. The runtime/* workspaces specifically depend on the desktop environment for message passing and process management.

How do I fix missing Electron binaries after installation?

Run the verification script manually:

node apps/desktop/scripts/ensure-electron-install.mjs

This checks node_modules/electron/dist and re-triggers trusted dependency installation if binaries are absent. If issues persist, delete node_modules and re-run npm run desktop:install to force a clean fetch of all native dependencies.

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