Install Hope Agent

Stable downloads and platform availability; Windows and Linux support is currently experimental.

The current stable release is v0.56.0. Regular macOS releases target Apple Silicon; Windows x64 and Linux x64 / arm64 support is experimental. Install with a package manager or download the matching GitHub Release asset.

macOS

Homebrew

Recommended
bash
brew tap shiwenwen/hope-agent
brew install --cask hope-agent

Already have Hope Agent.app installed manually? Append --adopt to let the cask take over your existing same-version app without re-downloading, or --force to overwrite.

Manual install (DMG)

Download the v0.56.0 Apple Silicon DMG and drag into Applications. Mirror: Apple Silicon.

If macOS reports "damaged" or "cannot verify the developer" on first launch, run in Terminal:

bash
sudo xattr -cr /Applications/Hope\ Agent.app
sudo codesign --force --deep --sign - /Applications/Hope\ Agent.app

The Intel Mac (x64) installer is built separately and uploaded after the main release. The v0.56.0 Release does not yet list Hope.Agent_0.56.0_x64.dmg; recheck the assets before downloading. While it is absent, neither Homebrew nor the download page can supply this version for Intel Macs. The Apple Silicon (arm64) installer cannot run on an Intel Mac.

Windows

Scoop

Recommended
powershell
scoop bucket add hope-agent https://github.com/shiwenwen/scoop-hope-agent
scoop install hope-agent

Manual install (installer)

Download Hope.Agent_*-setup.exe from Releases and double-click. Mirror: x64 installer. Windows is not yet fully tested — please file issues if anything breaks.

If Windows reports "MSVCP140_1.dll was not found" or a similar missing VCRUNTIME140.dll / MSVCP140.dll error on launch, install the Microsoft Visual C++ 2015–2022 Redistributable (x64) and relaunch.

x64 only.

Linux

Arch Linux / Manjaro (AUR)

bash
yay -S hope-agent-bin   # or paru / any AUR helper

Pre-built binary package (repackaged from the GitHub Release .deb) — no source compilation.

Debian / Ubuntu (apt)

bash
curl -fsSL https://repo.hopeagent.ai/pubkey.gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hope-agent.gpg
echo "deb [signed-by=/usr/share/keyrings/hope-agent.gpg] https://repo.hopeagent.ai/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/hope-agent.list
sudo apt update
sudo apt install hope-agent

Fedora / RHEL / CentOS (dnf / yum)

bash
sudo curl -fsSL https://repo.hopeagent.ai/rpm/hope-agent.repo \
  -o /etc/yum.repos.d/hope-agent.repo
sudo dnf install hope-agent     # or `sudo yum install hope-agent`

The older sudo dnf config-manager --add-repo … form has been removed in dnf5 (Fedora 41+); the curl variant above works on dnf4 / dnf5 / yum / zypper alike.

openSUSE users:

bash
sudo zypper addrepo https://repo.hopeagent.ai/rpm/hope-agent.repo
sudo zypper install hope-agent

Manual install (AppImage / deb / rpm)

From Releases (filenames include the arch suffix — pick _amd64 / _arm64 for deb/AppImage or .x86_64 / .aarch64 for rpm):

  • AppImage: Hope.Agent_*.AppImage — chmod +x and run. Mirror: amd64 · aarch64
  • Debian / Ubuntu: Hope.Agent_*.deb — sudo dpkg -i Hope.Agent_*.deb. Mirror: amd64 · arm64
  • Fedora / RHEL: Hope.Agent_*.rpm — sudo rpm -i Hope.Agent_*.rpm. Mirror: x86_64 · aarch64

Both amd64 (x86_64) and arm64 (aarch64) native builds are published, covering desktops, Raspberry Pi 4/5, Apple Silicon Macs running Asahi Linux, and Graviton / Ampere cloud VMs. apt and dnf automatically pick the right arch via dpkg --print-architecture / $basearch.

First launch & updates

  1. First launch: pick a provider template → paste an API key / sign in with Codex OAuth → chat.
  2. The desktop updater prefers the repo.hopeagent.ai mirror and falls back to GitHub Releases. Check Settings → About, or ask Hope Agent to upgrade. Updater downloads are verified with the built-in public key.
  3. Homebrew / AUR / Scoop installs can use the same updater; the package manager may still record the initially installed version.
  4. For local models, first install the runtime manually from Ollama, then return to Settings to download and select a model.

Before remote access, configure an Owner Token in Settings → Server, then bind to 0.0.0.0:8420. The browser login exchanges it for a protected session; never put the Root Token in a URL. Use an HTTPS reverse proxy for public access.

Looking for a specific build? Browse all platform packages on the releases page.Releases