Install guide

Command-line downloads

On macOS or Linux, install GitHub CLI (gh) from cli.github.com. These commands list actual published installers and download the filename you choose. A release must exist first.

gh release view --repo asgeorgia/haloagents --json tagName,assets --jq '.tagName, (.assets[].name)'
uname -sm
mkdir -p "$HOME/Downloads/Halo"
printf 'Enter the exact installer filename: '
IFS= read -r HALO_ASSET
if [ -n "$HALO_ASSET" ]; then
  gh release download --repo asgeorgia/haloagents --pattern "$HALO_ASSET" --dir "$HOME/Downloads/Halo"
fi

Choose a macOS DMG for Apple Silicon (arm64) or Intel (x64), or a Linux AppImage, DEB or RPM matching your processor. Check the release notes if a filename omits its architecture. Verify the publisher before opening. Run only the matching command below, in the same terminal session.

# macOS DMG: then drag Halo to Applications
open "$HOME/Downloads/Halo/$HALO_ASSET"

# Linux AppImage
chmod +x "$HOME/Downloads/Halo/$HALO_ASSET"
"$HOME/Downloads/Halo/$HALO_ASSET"

# Debian / Ubuntu DEB (alternative)
sudo apt install "$HOME/Downloads/Halo/$HALO_ASSET"

# Fedora / RHEL RPM (alternative)
sudo dnf install "$HOME/Downloads/Halo/$HALO_ASSET"

The repository README includes downloads for specific versions. Public releases need no private token; private access requires gh auth login. Halo needs a graphical desktop. Other Unix systems, including BSD and Solaris, have no native Halo installers; downloading a Linux package does not make them supported.

macOS

  1. 01Open the .dmg and drag Halo into Applications.
  2. 02First launch: right-click Halo → Open, then confirm.
  3. 03Allow System Settings → Privacy & Security → Accessibility so Halo can type in other apps.

Windows

  1. 01Run Halo-Setup.exe. If SmartScreen appears, choose More info → Run anyway.
  2. 02Prefer no install? Use the portable .exe.

Linux

  1. 01AppImage: chmod +x Halo-*.AppImage, then run it.
  2. 02Debian/Ubuntu: sudo apt install ./halo-agent_*_amd64.deb
  3. 03Fedora/RHEL: sudo dnf install ./halo-agent-*.rpm
  4. 04On Wayland, typing into other apps may need X11 or XWayland.

Local model (offline)

  1. 01Install Ollama from ollama.com and keep it running.
  2. 02Halo pulls your chosen model automatically (default qwen2.5:7b-instruct). Try llama3.1, deepseek-r1 or qwen3 in settings.

Cloud models (optional)

  1. 01Click ⚙ in Halo, choose Anthropic, OpenAI, DeepSeek or OpenRouter, and paste your API key.
  2. 02Keys stay on your computer. Halo only uses the cloud when the local model can't finish.

Using Halo

  1. 01Ctrl/Cmd+Shift+Space shows or hides the panel. Press – to shrink it to a floating orb.
  2. 02Pick File access: Minimal (apps + Desktop/Documents/Downloads) or Entire file system.
  3. 03Halo asks before moving files or typing. You can switch this off in settings.
  4. 04Enable Launch at login from the tray icon.

Build from source

  1. 01Download the source zip, install Node.js 20+, then run npm install.
  2. 02npm start to run, or npm run dist:mac / dist:win / dist:linux to build installers.
  3. 03Pushing a tag such as v1.4.0 to GitHub builds every platform automatically.

Daily updates

  1. 01Update-enabled builds check published releases at github.com/asgeorgia/haloagents once every 24 hours while Halo is running, and when it next opens or wakes if a check is overdue.
  2. 02New releases download in the background on installed Windows builds, signed macOS builds and writable Linux AppImages. Halo asks before restarting; active tasks are not interrupted.
  3. 03Use Check for updates or Install update and restart in the tray menu. If you are offline, Halo retries later without stopping local work.
  4. 04Portable Windows builds and Linux .deb/.rpm packages check daily too, but require you to download and install the new release yourself.
  5. 05A code push alone does not distribute an update: increase the desktop app version and push its matching v-prefixed tag. The release must include installers and latest*.yml update metadata.
  6. 06macOS automatic updates require a Developer ID signing certificate. Versions installed before update support was added need a one-time manual upgrade.