# Install Hope Agent

Canonical page: https://www.hopeagent.ai/en/install

The current stable release is v0.60.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

```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.60.0 Apple Silicon DMG](https://github.com/shiwenwen/hope-agent/releases/download/v0.60.0/Hope.Agent_0.60.0_aarch64.dmg) and drag into Applications. Mirror: [Apple Silicon](https://repo.hopeagent.ai/download/latest/Hope.Agent_aarch64.dmg).

> 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
> ```

v0.60.0 includes an [Intel Mac (x64) DMG](https://github.com/shiwenwen/hope-agent/releases/download/v0.60.0/Hope.Agent_0.60.0_x64.dmg). The Apple Silicon (arm64) installer cannot run on an Intel Mac; check [Release assets](https://github.com/shiwenwen/hope-agent/releases) for architecture availability in other versions.

## Windows

### Scoop

```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](https://github.com/shiwenwen/hope-agent/releases) and double-click. Mirror: [x64 installer](https://repo.hopeagent.ai/download/latest/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)](https://aka.ms/vs/17/release/vc_redist.x64.exe) 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](https://github.com/shiwenwen/hope-agent/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](https://repo.hopeagent.ai/download/latest/Hope.Agent_amd64.AppImage) · [aarch64](https://repo.hopeagent.ai/download/latest/Hope.Agent_aarch64.AppImage)
- Debian / Ubuntu: `Hope.Agent_*.deb` — `sudo dpkg -i Hope.Agent_*.deb`. Mirror: [amd64](https://repo.hopeagent.ai/download/latest/Hope.Agent_amd64.deb) · [arm64](https://repo.hopeagent.ai/download/latest/Hope.Agent_arm64.deb)
- Fedora / RHEL: `Hope.Agent_*.rpm` — `sudo rpm -i Hope.Agent_*.rpm`. Mirror: [x86_64](https://repo.hopeagent.ai/download/latest/Hope.Agent.x86_64.rpm) · [aarch64](https://repo.hopeagent.ai/download/latest/Hope.Agent.aarch64.rpm)

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](https://ollama.com/download), 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.

## Documentation and source

- [Hope Agent — Open-source AI assistant with memory and tools](https://www.hopeagent.ai/en)

- [Hope Agent User Guide](https://www.hopeagent.ai/en/guide)

- [Running modes](https://www.hopeagent.ai/en/running-modes)

- [Features](https://www.hopeagent.ai/en/features)

- [Self-Hosting](https://www.hopeagent.ai/en/self-host)

- [Frequently asked questions](https://www.hopeagent.ai/en/faq)

- [What's new](https://www.hopeagent.ai/en/changelog)

- [GitHub](https://github.com/shiwenwen/hope-agent)

- [Releases](https://github.com/shiwenwen/hope-agent/releases)

- [MIT](https://github.com/shiwenwen/hope-agent/blob/main/LICENSE)