- Docs
- Getting Started
- Installation
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.
Download the desktop app
Section titled “Download the desktop app”Get the latest version from the download page. These are the files for version 0.2.1:
| System | File | Notes |
|---|---|---|
| Windows | HeadlessOS Setup 0.2.1.exe | Installer |
| Windows | HeadlessOS 0.2.1.exe | Portable, no install needed |
| macOS | HeadlessOS-0.2.1-universal.dmg | Apple silicon and Intel |
| macOS | HeadlessOS-0.2.1-universal-mac.zip | Apple silicon and Intel |
| Linux | HeadlessOS-0.2.1.AppImage | Most distributions |
| Linux | headlessos-desktop_0.2.1_amd64.deb | Debian 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.
Install on Windows
Section titled “Install on Windows”- Run the installer, or run the portable
.exe. - If SmartScreen shows “Windows protected your PC”, choose More info, then Run anyway.
Install on macOS
Section titled “Install on macOS”- Open the
.dmgand drag HeadlessOS to Applications, or unzip the.zipand move the app there. - Open the app once. macOS blocks it.
- 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:
xattr -cr /Applications/HeadlessOS.appTo reach a device on your local network, the app also needs local network access.
Install on Linux
Section titled “Install on Linux”Make the AppImage executable and run it:
chmod +x HeadlessOS-0.2.1.AppImage./HeadlessOS-0.2.1.AppImageOr install the .deb with your package manager:
sudo apt install ./headlessos-desktop_0.2.1_amd64.debRun from source
Section titled “Run from source”This runs the same app in your browser at localhost. You need Git, Node.js 20 or later and npm 9 or later.
git clone https://github.com/abhee235/headlessos.gitcd headlessosnpm installcp .env.example .envnpm run devOpen 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 installruns agit configstep that needs a Git checkout. - Keep the
.envfile.npm run devwon’t start without it. It lives in the repository root. In Windows Command Prompt, usecopy .env.example .env. - An API key is optional. You can leave the placeholder in
.envand 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.
Build the desktop app yourself
Section titled “Build the desktop app yourself”From the repository root:
npm installnpm run build --workspace=sharednpm run build:dist:winUse build:dist:mac or build:dist:linux for the other systems. The files appear in electron/dist/.
Update HeadlessOS
Section titled “Update HeadlessOS”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.
Uninstall HeadlessOS
Section titled “Uninstall HeadlessOS”| System | How |
|---|---|
| Windows | Remove it in Windows Settings, or delete the portable .exe |
| macOS | Delete HeadlessOS from Applications |
| Linux | Delete 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.