Install Locally

📦 Full installer list across platforms: Releases 🌏 Can't reach GitHub? Every installer is mirrored at <https://repo.hopeagent.ai/download/latest/> (Cloudflare R2, the same domain as the apt / dnf repos), and each manual-install entry below links the mirror directly. The desktop auto-updater prefers this mirror too, with GitHub as the fallback. Past versions are kept indefinitely under https://repo.hopeagent.ai/download/v<version>/.

macOS

Homebrew (recommended)

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 Hope.Agent_*.dmg from Releases and drag into Applications. Mirror: Hope.Agent_aarch64.dmg.

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

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

Regular releases provide native Apple Silicon (arm64) builds. Intel Mac (x64) packages are produced separately on demand: check that the target release actually contains an x64 DMG before installing. Homebrew and the download page cannot supply an Intel package when that asset is absent.

Launch modes

• Desktop GUI: Launchpad / Applications folder (click the Hope Agent icon), or open -a "Hope Agent" / hope-agent from a terminal
• Browser Web GUI: open <http://127.0.0.1:8420> after launching the desktop app, or run hope-agent server start to start only the service without a desktop window
• ACP (IDE integration): hope-agent acp

Windows

Scoop (recommended)

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: Hope.Agent_x64-setup.exe. 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.

Launch modes

• Desktop GUI: click "Hope Agent" in the Start menu, or hope-agent from PowerShell
• Browser Web GUI: open <http://127.0.0.1:8420> after launching the desktop app, or run hope-agent server start in PowerShell / cmd to start only the service without a desktop window
• ACP (IDE integration): hope-agent acp

Linux

Arch Linux / Manjaro (AUR)

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)

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)

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:

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.

Launch modes

• Desktop GUI: click "Hope Agent" in your app menu, or hope-agent from a terminal
• Browser Web GUI: open <http://127.0.0.1:8420> after launching the desktop app, or run hope-agent server start to start only the service without a desktop window
• ACP (IDE integration): hope-agent acp

First launch & auto-update

1. First launch wizard: pick a provider template → paste API key / sign in with Codex OAuth → chat.
2. Desktop builds ship with a built-in auto-updater (it reads the repo.hopeagent.ai mirror first and falls back to GitHub Releases). Go to Settings → About in-app to check for and install updates, or just tell the model "upgrade" / "check for updates" in chat. Installers fetched by the updater are signature-verified against the built-in public key — the mirror and GitHub go through the identical check. (Manual downloads are installed by your OS and do not pass through it.)
3. Versions installed via Homebrew / AUR / Scoop also receive updates through the built-in updater; the package manager's recorded version stays pinned to the initial install version and does not affect functionality.

To connect from a phone or another computer, set an API key under Settings → Server and change the bind address to 0.0.0.0:8420. After restarting, open http://<IP of the device running Hope Agent>:8420. Never expose the port to a LAN or the public internet without authentication; for public access, put it behind an HTTPS reverse proxy. See the Docker deployment guide.

Self-hosting (Docker)

For running Hope Agent on a home NAS / VPS / homelab and accessing the Web GUI from a browser:

docker run -d \
  --name hope-agent \
  -p 127.0.0.1:8420:8420 \
  -v hope-data:/data \
  ghcr.io/shiwenwen/hope-agent:latest

Once the container is running, open <http://127.0.0.1:8420> in a browser and follow the onboarding wizard to configure provider API keys. The image covers linux/amd64 + linux/arm64 (including Apple Silicon and Raspberry Pi) and is auto-built on every release tag.

For docker-compose, the optional Ollama sidecar for local LLMs, LAN exposure, reverse proxy + TLS, and upgrade flow, see docs/deployment/docker.en.md.

Quick Start