holaOS

环境要求

• macOS、Linux 或 WSL 环境（一键脚本面向全新机器引导）
• git（可用 git --version 验证）
• Node.js 与 npm（一键脚本会在缺失时安装 Node.js 24.14.1）
• 仓库根目录 .nvmrc 固定了 Node 版本；使用 nvm 可选，非必需

安装与启动步骤

1. 1一键安装

   在全新 macOS/Linux/WSL 机器上运行官方安装脚本，并加 --launch 参数直接启动桌面应用。

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

   复制

2. 2检查本地依赖

   手动安装前先确认 git、node、npm 版本可用；若已用 nvm，可在仓库根目录执行 nvm use 切换版本。

   git --version
   node --version
   npm --version

   复制

3. 3安装桌面依赖

   在仓库根目录安装桌面端所需依赖，这是本地桌面开发的基础安装流程第一步。

   npm run desktop:install

   复制

4. 4创建环境文件

   从模板复制本地环境文件，按需修改；规范路径是 apps/desktop/.env，请尽量贴近模板只改必要值。

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

   复制

5. 5准备运行时包

   生成本地运行时 bundle。若要改用已发布的运行时产物，可执行 npm run desktop:prepare-runtime。

   npm run desktop:prepare-runtime:local

   复制

6. 6类型检查校验

   启动 Electron 前的快速校验，确认环境与代码没有明显问题。

   npm run desktop:typecheck

   复制

7. 7启动桌面应用

   以开发模式启动。predev 钩子会校验环境、重建原生模块并确认运行时包已就位。

   npm run desktop:dev

   复制

关键配置

如何确认成功

执行 npm run desktop:typecheck 无报错，且 npm run desktop:dev 后 Electron 桌面窗口成功打开即启动成功。

常见问题

注意事项

• 本地优先（local-first），数据不会离开你的机器。
• 新配置请使用 apps/desktop/.env，旧的 desktop/.env 目前仍被接受但建议迁移。
• 安装脚本默认把仓库克隆到 ~/holaboss-ai，可通过 --dir 指定其他目录。
• 不指定 --launch 时安装脚本只做安装与校验，不会自动启动桌面应用。