Skip to content
GitHub Download

Installation

Install HeadlessOS on Windows, macOS or Linux, get past first-launch warnings, run it from source, and update or uninstall it.

HeadlessOS runs on your computer, not on your server. You can install the desktop app, or run it from source in a browser. Your server needs nothing beyond SSH, though some apps use tools you may already have. See what your server needs.

Get the latest version from the download page. These are the files for version 0.2.1:

SystemFileNotes
WindowsHeadlessOS Setup 0.2.1.exeInstaller
WindowsHeadlessOS 0.2.1.exePortable, no install needed
macOSHeadlessOS-0.2.1-universal.dmgApple silicon and Intel
macOSHeadlessOS-0.2.1-universal-mac.zipApple silicon and Intel
LinuxHeadlessOS-0.2.1.AppImageMost distributions
Linuxheadlessos-desktop_0.2.1_amd64.debDebian and Ubuntu

You need 64-bit Windows 10 or 11, macOS 11 or later, or a 64-bit Linux desktop.

The builds are unsigned, so Windows and macOS warn you on first launch. Download them only from the download page or the project’s GitHub releases.

  1. Run the installer, or run the portable .exe.
  2. If SmartScreen shows “Windows protected your PC”, choose More info, then Run anyway.
  1. Open the .dmg and drag HeadlessOS to Applications, or unzip the .zip and move the app there.
  2. Open the app once. macOS blocks it.
  3. Go to System Settings → Privacy & Security and choose Open Anyway.

If macOS says the app is damaged, run this in Terminal and open it again:

Terminal window
xattr -cr /Applications/HeadlessOS.app

To reach a device on your local network, the app also needs local network access.

Make the AppImage executable and run it:

Terminal window
chmod +x HeadlessOS-0.2.1.AppImage
./HeadlessOS-0.2.1.AppImage

Or install the .deb with your package manager:

Terminal window
sudo apt install ./headlessos-desktop_0.2.1_amd64.deb

This runs the same app in your browser at localhost. You need Git, Node.js 20 or later and npm 9 or later.

Terminal window
git clone https://github.com/abhee235/headlessos.git
cd headlessos
npm install
cp .env.example .env
npm run dev

Open http://localhost:3000. npm run dev starts the backend on port 3001 and the web app on port 3000.

  • Clone with Git. Don’t use a ZIP download: npm install runs a git config step that needs a Git checkout.
  • Keep the .env file. npm run dev won’t start without it. It lives in the repository root. In Windows Command Prompt, use copy .env.example .env.
  • An API key is optional. You can leave the placeholder in .env and add a key later in Settings → AI / LLM.
  • Logs go to your terminal. The browser version has no log file and no Open log button.

From the repository root:

Terminal window
npm install
npm run build --workspace=shared
npm run build:dist:win

Use build:dist:mac or build:dist:linux for the other systems. The files appear in electron/dist/.

The app doesn’t update itself. Download the new version from the download page and install it over the old one, or replace the portable file or AppImage. Your saved servers stay, because they’re kept in your home folder, not with the app.

The changelog lists what changed in each version.

SystemHow
WindowsRemove it in Windows Settings, or delete the portable .exe
macOSDelete HeadlessOS from Applications
LinuxDelete the AppImage, or run sudo apt remove headlessos-desktop

Uninstalling leaves your data in ~/.headlessos/, which is C:\Users\<you>\.headlessos on Windows. Delete that folder to remove your saved servers, passwords, API keys, traces and logs. Your servers aren’t affected.