Hope Agent
A local-first desktop assistant that carries your tasks and memory across devices.
What does this agent do, and when should you use it?
Hope Agent is a personal AI assistant centered on a local desktop experience, with an option to run persistently as a service with a Web GUI. Its architecture combines a Rust core, a Tauri 2 desktop shell, and a React 19 frontend across Desktop, Server + Web GUI, and ACP modes. It keeps projects, chats, memories, goals, workflows, and background tasks in one system, with state stored by default in ~/.hope-agent/. Beyond chat, it can operate on files, run bash, call MCP services, control a browser and macOS with approval, and coordinate sub-agents. It also includes a Markdown-based knowledge space and a design space for producing exportable deliverables.
During onboarding, the user selects a Provider template and supplies an API key or signs in through Codex OAuth. Chats can be placed in Projects; global, project, and Agent memories are stored in layers and retrieved through full-text and vector search. A user can define a Goal and success criteria, while Workflow records stages, conditions, parallel work, tools, diffs, reviews, and verification for an execution; Loop resumes work on an interval, condition, or event, and Task shows progress. Subject to centralized approval, it can run bash, read and write files, call MCP through OAuth 2.1 transports, connect workspaces, control macOS, and operate pages through a controllable browser. The design space can produce web pages, mobile prototypes, presentations, and other artifacts for export as HTML, PNG, PDF, PPTX, MP4, or ZIP; the knowledge space reads and writes Markdown and supports search, backlinks, graphs, and Obsidian vault binding.
- An individual tracking a multi-step research or work outcome on a Mac can use Goals, Workflows, Loops, and background Tasks to continue and resume execution.
- A user running a personal assistant on a NAS, home server, or VPS can use hope-agent server, access the Web GUI in a browser, and keep IM channels and scheduled work online.
- A knowledge worker maintaining Markdown notes or an existing Obsidian vault can archive material, retrieve it, and review AI-generated organization suggestions in the knowledge space.
- A product or design practitioner who needs web pages, mobile prototypes, presentations, or posters from text or reference images can preview, refine, version, and export results in the design space.
- An advanced user combining APIs, shell commands, files, and MCP services can delegate work between the main chat and dynamic sub-agents under approval controls.
What are this agent's strengths and limitations?
- The same ha-core powers desktop, headless Server + Web GUI, and ACP modes, allowing chats, memory, and task state to continue between local and self-hosted environments.
- It combines Goals, Workflows, Loops, and Tasks with persistent execution records that can be paused, resumed, and conservatively recovered for work that extends beyond a single chat.
- It includes an MCP client, bash, file operations, browser control, and macOS control, with centralized approval for side effects and an optional Docker sandbox.
- Its Markdown knowledge space and design space cover both knowledge maintenance and production of deliverables exportable as HTML, PNG, PDF, PPTX, MP4, and ZIP.
- It documents 40+ Provider templates, 300+ preset models, Ollama local models, and API-key rotation, avoiding a single-provider model path.
- The complete desktop experience is explicitly centered on macOS; Linux and Windows are labeled experimental, and Windows is x64 only.
- Cloud models require the user’s own Provider API key or Codex OAuth, while local models require Ollama installation and model downloads.
- File writes, commands, browser control, and computer control have real side effects; approvals and Docker sandboxing still require the user to configure permissions and review actions.
- Remote access requires changing the listener and configuring an API key; public exposure additionally requires the user to set up an HTTPS reverse proxy.
- State lives by default in ~/.hope-agent/; the materials document Obsidian binding but do not document a general-purpose migration or import/export process.
How do you install or deploy this agent?
On macOS, run:brew tap shiwenwen/hope-agentbrew install --cask hope-agent
For self-hosting, run:docker run -d --name hope-agent -p 127.0.0.1:8420:8420 -v hope-data:/data ghcr.io/shiwenwen/hope-agent:latest
After the container starts, open http://127.0.0.1:8420. First use requires selecting a Provider template and providing that provider’s API key, or signing in with Codex OAuth; the local-model path installs and configures Ollama from Settings.
How do you use this agent?
Launch the desktop app, or run hope-agent server start and open http://127.0.0.1:8420. After configuring a Provider, start a chat; for ongoing work, define a Goal and success criteria, execute it with a Workflow, and set a Loop condition for future progress. For an IDE backend, run hope-agent acp. To access it from another device, set the server listener to 0.0.0.0:8420 and configure an API key; public deployment should place an HTTPS reverse proxy in front of it.
How does this agent compare with similar options?
Compared with using Ollama directly, Hope Agent presents Ollama as a GUI-managed local runtime and OpenAI-compatible endpoint; models such as Qwen and Gemma are still distributed through the Ollama model library.