# What Dependencies Are Required to Run HolaOS? Complete Installation Guide

> Discover the essential dependencies for running HolaOS. Learn about root-level tooling, workspace packages, and desktop libraries needed for installation. Get started now!

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

---

**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`](https://github.com/holaboss-ai/holaOS/blob/main/package.json).

### Turbo Task Runner

**Turbo** serves as the monorepo task runner, orchestrating builds and scripts across all workspaces. The root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/package.json) carries the heaviest dependency load, spanning lines 62-124.

### Electron Build Tools

```json
{
  "@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`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) declares conditional dependencies at lines 126-131.

### macOS-Only Features

```json
{
  "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

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

```bash

# 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`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) (root) | Declares workspaces, Turbo configuration, and trusted native dependencies |
| [`apps/desktop/package.json`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/package.json) | Complete inventory of UI libraries, SDKs, and Electron tools |
| [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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`](https://github.com/holaboss-ai/holaOS/blob/main/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:

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