hope-agent

Watch Hope Agent in 3 minutes

English narration and captions. Explore goals, tools, memory, knowledge, and design in one desktop workflow.

https://github.com/user-attachments/assets/e1728465-0f5b-47a6-8af8-b9806067a6b4

---

Hope Agent is a local-first, desktop-first personal AI agent that can also run continuously as a service. It opens like mature desktop software while offering real agentic capability: understanding long-term context, using tools to complete work, and reliably pursuing goals even after you step away.

Hope Agent did not begin after “desktop AI agents” became a popular category. We started building it when desktop agents were still uncommon and Codex itself was in an earlier form. We have always focused on the product itself, not on manufacturing attention. As more products have moved in the same direction, they have reinforced our original conviction: AI assistants will move beyond the chat box and become personal software people can trust with long-running work.

Contents

• Who is it for?
• One task, across devices
• Core Capabilities
• Capability Overview
• Quick Start
  • Install Locally
  • Self-hosting (Docker)
  • For developers
• Run Modes
• Ecosystem
• Project Structure
• Documentation
• Contributing
• Community
• Acknowledgements
• Star History
• License

Who is it for?

• Independent developers who want to discuss a change, inspect a repository, edit files, and run checks in one desktop workspace, with tool permissions and approvals controlling execution.
• People working with research and documents who want to organize sources in Knowledge Space, recall useful context across conversations, and turn a brief into a draft or design to review.
• NAS and self-hosting users who want one always-on instance they can reach through a browser or a configured IM channel, with scheduled tasks and conversation history kept on that host.

One task, across devices

For example, start a research brief at your desk, add a requirement from your phone, then review the draft when you return:

1. Start on desktop. Open a conversation and ask Hope Agent to prepare a brief from sources you provide. Configure an IM channel on this same instance and hand the conversation over to your chat there.
2. Continue through IM. In that chat on your phone, add a requirement or ask for progress. The attached conversation keeps its history; tool actions still follow the instance's permissions and approvals.
3. Return to desktop. Open the same conversation to review the reply and any generated files, then ask for revisions.

Keep the host running and connected. This example uses one instance and its session store; separate installations do not automatically synchronize. A browser can also access the same instance when remote access is configured with authentication (and HTTPS for public access). See session handover and remote deployment.

Core Capabilities

Capability Overview

🎨 Design & knowledge

🧭 Long-running work & autonomy

Mental model: Goal defines the outcome, Workflow performs one concrete execution, Loop decides when to advance again, Task exposes current progress, and Mode controls execution autonomy. They compose cleanly but can also be used independently.

🧠 Memory & growth

🛠 Tools & connections

🌐 Desktop, service & cross-device

🛡 Security & reliability

For the complete version history, see CHANGELOG.md. Implementation details live under docs/architecture/.

Quick Start

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.

For developers

git clone https://github.com/shiwenwen/hope-agent.git
cd hope-agent
pnpm install
pnpm dev:desktop       # default desktop dev (frontend + Rust hot reload)

# Other useful commands
pnpm typecheck         # frontend typecheck (tsc -b)
pnpm lint              # lint
pnpm tauri build       # production build

Desktop development enables extra binaries only when they are needed, so ordinary UI and business-logic work does not wait for unrelated Rust crates:

Command	Browser Host	Eval Sidecar	Use case
pnpm desktop	As selected	As selected	Interactively choose a mode
pnpm dev:desktop	Not built	Not built	Default UI / business development
pnpm dev:desktop:browser	Built	Not built	Chrome extension integration
pnpm dev:desktop:eval	Not built	Built	Evaluation feature development
pnpm dev:desktop:full	Built	Built	Full desktop capability check

The default command delegates to pnpm exec tauri dev --config src-tauri/tauri.dev.conf.json. Prefer the scripts above so startup flags and optional-component conventions stay aligned. Production pnpm tauri build still builds and bundles both the Browser Host and Eval Sidecar.

For local Web GUI development with live reload, run pnpm dev:desktop and open http://localhost:1420 in your browser. That is the Vite dev server, sharing the same frontend HMR as the Tauri window. http://localhost:8420 is the embedded HTTP/WS server's static Web GUI entry, served from dist/ / the embedded bundle, so it behaves like the packaged browser entry and does not HMR with source changes. If your local server has an API key enabled, the 1420 page may get 401s from 8420; for development, temporarily clear the Server API Key in Settings and restart.

Run Modes

Mode	How to start	When to use
Desktop GUI	Double-click the app / pnpm dev:desktop	The most complete entry point: full GUI plus an embedded HTTP/WS server, so the desktop can serve remote clients while you use it
Server + Web GUI (HTTP/WS)	server start subcommand; server install registers a launchd / systemd service	Headless always-on daemon for IM channels and cron jobs; the React frontend is rust-embed-baked into the server binary, so opening http://<server>:port in any browser gives you the full Web GUI — phone, tablet, any computer can connect directly without installing a client
ACP (stdio)	acp subcommand	IDE integration — any ACP-capable editor can call Hope Agent as its agent backend

All three modes share the same ha-core core. Config, sessions, and memories live under ~/.hope-agent/.

Ecosystem

Project Structure

Layered multi-crate Cargo workspace: kernel capabilities live in ha-core; self-contained feature domains live in feature crates (ha-acp / ha-browser / ha-design / ha-mac / ha-mcp / ha-media / ha-pet / ha-updater / ha-vcs / ha-weather, with more moving out as the split continues):

crates/
  ha-base/           Infrastructure foundation (paths / logging / platform / security)
  ha-config-schema/  AppConfig wire types (pure data definitions)
  ha-core/           Rust core library (zero Tauri deps) — kernel + most business logic
  ha-acp/            ACP feature crate (stdio server mode + external agent control plane)
  ha-browser/        Browser feature crate (extension backend / CDP / browser tool)
  ha-design/         Design space feature crate (artifacts store + compile/export + 3 tools)
  ha-mac/            macOS control feature crate (Accessibility / screenshot / mac_control tool)
  ha-mcp/            MCP client feature crate (McpManager / transports / OAuth / two tools)
  ha-media/          Media feature crate (image/audio generation adapters + STT engines + two tools)
  ha-pet/            Desktop pet feature crate (sprite store / import / creator / activity projection)
  ha-updater/        Self-update feature crate (depends on ha-core, wired by shells)
  ha-vcs/            VCS & local-exec feature crate (git control-plane ops + Docker sandbox machinery + SearXNG deploy)
  ha-weather/        Weather feature crate (depends on ha-core, wired by shells)
  ha-server/         axum HTTP/WS daemon (thin shell)
  ha-browser-host/   Browser helper process
  ha-eval-spec/      Evaluation protocol (no ha-core dependency)
  ha-eval/           Evaluation CLI
src-tauri/       Tauri desktop shell (thin shell)
src/             React 19 + TypeScript frontend
skills/          Bundled skills (ship with the app)

For constraints across modules and development entry points, see AGENTS.md. Module designs are in the technical documentation index.

Documentation

• 📖 User Guide — the complete user manual: installation, getting started, and how to use and configure every feature (简体中文)
• 🏗️ Technical docs — architecture and implementation details (for developers)

Contributing

The main branch is under active development — issues and PRs are welcome. Before contributing, read the global constraints in AGENTS.md, then follow the documents relevant to your changes. Frontend conventions are in src/AGENTS.md.

Common commands:

pnpm dev:desktop                  # default desktop dev
cargo check --workspace              # Rust dep / type check
cargo test -p ha-base -p ha-config-schema -p ha-core -p ha-acp -p ha-browser -p ha-design -p ha-mac -p ha-mcp -p ha-media -p ha-pet -p ha-updater -p ha-vcs -p ha-weather -p ha-server   # core tests
node scripts/sync-i18n.mjs --check   # i18n completeness check

Community

• 🐛 Issues — bug reports, feature requests
• 💡 Discussions — usage, ideas, Q&A
• ⭐ If Hope Agent helps you, consider giving it a star on GitHub
• 📮 Roadmap, a dedicated docs site, and more community channels are on the way

Acknowledgements

• Ollama — the one-click local LLM experience is built on top of Ollama's local runtime and its OpenAI-compatible endpoint; Hope Agent only wraps the GUI layer, while Qwen / Gemma and other models are distributed through the Ollama model library
• ClawHub / SkillHub — public skill discovery sources for Hope Agent
• Tauri, axum, React, shadcn/ui, Streamdown, Radix UI, and the rest of the open source stack Hope Agent stands on
• Everyone who has filed issues, tested builds, and given feedback along the way

Star History

License

MIT