Installing holaOS Locally: the One-Line Script, or the Official Five Manual Steps

holaOS is a local-first agentic workspace where Claude Code, Codex and its own agent share one memory and one set of tools. Here is the install flow, taken directly from the official README and verified 2026-09-07.

1. Pick a route first

The README lists three ways to run it:

If you just want to use it, download the desktop app and skip the rest. What follows is the self-hosted route.

2. The fast path: one-line install

The repository installer, for a fresh macOS, Linux or WSL machine:

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

One note before running it: piping a remote script straight into a shell is convenient and means you are trusting that source completely. The careful version is download install.sh, read it, then run it — particularly since it installs Node, clones the repo and creates an environment file. That is general practice, not a comment on holaOS.

The --launch flag starts the app after installing; omit it to install only.

3. Manual install: the official five steps

The README says outright that you likely will not need this, because the one-line install runs the same setup. Use it when you want to inspect each step.

Check prerequisites first:

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

The repo pins its Node version in a root .nvmrc; if you already use nvm, running nvm use in the repo root picks it up. nvm is optional, not required.

Then:

1. Install desktop dependencies from the repository root:

   npm run desktop:install
   

2. Create your local environment file:

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

   The canonical path is apps/desktop/.env. The README notes that legacy desktop/.env files are still accepted for now, but new setups should use apps/desktop/.env. This is the easiest step to get wrong by following an older guide.
3. Prepare the local runtime bundle:

   npm run desktop:prepare-runtime:local
   

4. Optional validation pass before launching Electron:

   npm run desktop:typecheck
   

5. Start the desktop app in development mode:

   npm run desktop:dev
   

   Per the README, the predev hook validates the environment, rebuilds native modules, and confirms a staged runtime bundle exists.

4. Two runtime commands, two purposes

Commonly confused:

• npm run desktop:prepare-runtime:local — build from local runtime code. Use this while actively changing runtime code.
• npm run desktop:prepare-runtime — fetch the latest published runtime. Use this to verify the desktop against a known release artifact.

5. Handing the install to your coding agent

A genuinely useful section of the README: if you use Codex, Claude Code, Cursor, Windsurf or another coding agent, the project supplies a paste-ready instruction. In summary, it tells the agent to:

Run the holaOS install script; install git and Node.js 24.14.1/npm if missing; clone or update the repo into ~/holaboss-ai unless another --dir is given; run desktop:install; create apps/desktop/.env from the example if needed; run desktop:prepare-runtime:local and desktop:typecheck; and only run desktop:dev if asked with --launch. If Electron cannot open, stop after verification and report the next manual step.

Two things worth copying from how that is written: it pins an exact Node version, and it tells the agent to stop and report on failure rather than improvising.

The detailed bootstrap lives in the repo’s INSTALL.md runbook.

6. The licence deserves a real read

From the README’s OSS release notes:

License: modified Apache 2.0 with additional commercial-distribution and branding conditions.

That is why the GitHub API reports NOASSERTION for this repo — it is not a standard licence, so detection declines to classify it.

Practically: self-hosting for personal use is unlikely to be a problem, but read the LICENSE file before bundling it into a commercial product, redistributing it, or using the branding. Do not read “Apache 2.0” as standard Apache 2.0.

Security issues are to be reported privately to admin@holaboss.ai rather than as public issues.

7. What to do first after it launches

Based on the architecture the README describes:

1. Connect one integration (Gmail, Notion, Slack, GitHub and Linear are all one-click OAuth) and see whether the approval flow suits you — every action asks first.
2. Open the memory folder. Memory is plain local files you can read and edit, and that is the biggest difference from other agent products.
3. Then decide about a second agent. Shared memory only shows its value once two agents use it.

For background on the project itself, see holaOS hit 11k stars in under six months.

Source: the holaOS README, read directly on 2026-09-07; all commands are quoted from the official documentation. Install details change between versions — follow the repo’s INSTALL.md, and read the LICENSE file yourself. Related agent pricing is on our Claude tool page.