# Hope Agent: a desktop AI agent that keeps working after you close the chat

> Hope Agent is a Rust and Tauri desktop assistant that adds persistent memory, goal-driven execution and dynamic multi-agent workflows on top of a normal chat UI. It also runs headless in Docker, so the same session state can follow you from desktop to browser to NAS.

**shiwenwen/hope-agent** — 🦭 会记忆、能持续推进目标、会动态编排多 Agent 的跨端桌面 AI 助手，也可服务化常驻 NAS / 云端 | A cross-device desktop AI agent with memory, autonomous goals, dynamic workflows, and headless deployment

- Repository: https://github.com/shiwenwen/hope-agent
- Stars: 1,678 · Forks: 158
- Language: Rust
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/shiwenwen-hope-agent

## The gap Hope Agent is trying to fill

Most chat assistants forget. You explain your project on Monday, and on Tuesday you explain it again. Hope Agent is built around the opposite assumption: that an assistant should accumulate context about you, hold a goal across days, and keep making progress while you are not watching. The README frames this as a personal agent that opens like desktop software but behaves like an agent, calling out memory, autonomous goals and dynamic workflow orchestration as its three differentiators.

The target user is a single person, not a team. The repository topics include personal, desktop-app and local-ai, and the README repeatedly uses first-person framing (your chats, your Markdown notes, your Obsidian vault). Nothing in the repository describes multi-tenant accounts, role-based access or shared workspaces in the team sense. If you are looking for an agent platform to deploy for an organisation, this is aimed elsewhere.

## How the Rust workspace is split

The architecture is visible in Cargo.toml, which lists a workspace with roughly thirty members. Each capability gets its own crate: ha-memory, ha-goal, ha-workflow, ha-agent-loop, ha-agent-runtime, ha-cron, ha-knowledge, ha-design, ha-skills, ha-mcp, ha-browser, ha-server, ha-acp, ha-channel and more. That split is the clearest statement of how the project thinks about itself. Memory, goals and workflows are not features bolted onto a chat loop; they are separate crates with their own boundaries.

The frontend is a Vite and React 19 app under src/, and the desktop shell is Tauri 2 under src-tauri/. The server crate, ha-server, has a build.rs that embeds the built frontend into the binary via rust-embed. That detail matters for deployment: the Dockerfile builds the Vite output first, copies dist/ in before cargo build, and the server binary then carries the web GUI inside it. One binary serves both the API and the browser interface.

The README describes a mental model worth quoting because it clarifies the moving parts: Goal defines the final result, Workflow handles one concrete execution, Loop decides when to push again, Task shows current progress, and Mode controls how autonomous the agent is allowed to be. These can be combined or used independently. That is a more explicit decomposition than most agent projects offer, and it is also more to learn.

## Running it headless with Docker on port 8420

The repository ships a docker-compose.yml written as an official example. It pulls ghcr.io/shiwenwen/hope-agent:latest, binds only to loopback by default, and persists state to a named volume at /data. On first boot Docker generates an owner token and stores it under /data/credentials, so changing the port mapping does not silently disable authentication.

The compose file documents the sequence directly. Start the stack, then print the generated token, then open the browser and enter it once. The token is exchanged for an HttpOnly browser session.

```bash
docker compose up -d
docker compose exec hope-agent hope-agent server token show
```

Then open http://127.0.0.1:8420 and paste the token. The compose comments are explicit that the root token should never be placed in a URL, and that exposing the service beyond localhost means changing the port mapping to "8420:8420" and putting a TLS-terminating reverse proxy such as Caddy, Nginx or Traefik in front. There is a with-ollama profile for a local model sidecar, enabled with docker compose --profile with-ollama up -d.

Two environment variables are documented in the compose file: HA_API_KEY, which supplies an externally managed owner token, and HA_CORS_ORIGINS, needed only when a separately hosted web GUI calls the API cross-origin. The comments prefer HA_API_KEY_FILE with a mounted secret for production. The Dockerfile runs the container as a non-root user named hope with uid 1000, and uses HA_DATA_DIR as the configurable data location.

## Building from source and the desktop path

For the desktop app the README points at downloadable releases, and the repository carries packaging directories for homebrew, scoop, aur and linux-repo, which suggests the maintainer intends native package distribution rather than source builds for end users. The developer path is a pnpm workspace with a Rust toolchain pinned in rust-toolchain.toml.

The package.json defines the scripts a contributor would use. The dev script runs Vite alone, dev:desktop runs tauri dev with a separate dev config, and there are composite scripts that also start the browser host and the eval sidecar. The build script runs tsc -b followed by vite build.

```bash
pnpm install
pnpm dev:desktop
```

That starts the Tauri desktop shell against the dev server. For the browser-host and eval variants, package.json lists dev:desktop:browser, dev:desktop:eval and dev:desktop:full. Version syncing across the Rust crates and the Node package is handled by pnpm sync:version, which the Cargo.toml comments confirm keeps per-crate versions aligned. Note that package.json declares version 0.48.0 while the most recent GitHub release listed is v0.47.0, so the repository is one version ahead of the published release at the time of writing.

## Where the design creates real friction

The breadth is the problem as much as the selling point. The capability table lists a design space that generates web pages, mobile prototypes, slide decks, dashboards, posters, documents, emails, images, motion, audio and interactive components, with export to HTML, PNG, PDF, PPTX, MP4 and ZIP. It also lists a knowledge space that binds to an existing Obsidian vault, a Feishu workspace with 40+ tools, browser control with a live mirror, MCP with OAuth 2.1, and Hooks on 20+ lifecycle events. Each of those is a surface area that can break independently.

The release cadence reinforces the concern. The three most recent releases listed are v0.45.0 on 2026-09-06, v0.46.0 on 2026-09-07 and v0.47.0 on 2026-09-08, with the last push to main on 2026-09-09. Daily minor releases on a 0.x version line mean the project is not promising API or configuration stability. The README does mention configuration rollback and crash recovery as product features, which helps at runtime, but that is not the same as a documented migration path between versions. The README does not describe an upgrade procedure for existing installations.

Platform support is another boundary. The badges mark macOS as supported and Linux and Windows as experimental. If your team is Windows-first, you are on the experimental path. The Dockerfile adds a related constraint for self-hosters: both the build and runtime stages must stay on Debian trixie because the prebuilt ONNX Runtime binaries pulled in by fastembed for embeddings require glibc 2.38 or newer. Mixing a trixie build with a bookworm runtime will fail to load at startup, and the file says so explicitly. That is a narrow deployment window for anyone maintaining a base image policy.

## How it compares to a plain MCP client or a coding agent

The closest comparison is not another chatbot but the category of terminal coding agents. Those tools are session-scoped and repository-scoped: you start them in a project, they read files and run commands, and when you exit, the working state is largely gone. Hope Agent inverts that. Its ha-memory crate is described as layering memory by global, project and agent scope, with a distilled core that stays in context and detailed content retrieved on demand through full-text and vector search. The ha-goal and ha-workflow crates exist to carry work across sessions.

A plain MCP client is the other comparison point. Hope Agent includes an MCP client with OAuth 2.1 and multiple transports, but it wraps that in an approval layer, a Docker sandbox option, and Hooks that can fire on lifecycle events. The difference is that MCP is one integration among many rather than the product.

If all you need is a tool that edits code in one repository during a single sitting, the memory and goal machinery here is overhead you will pay for in configuration and in a fast-moving dependency. The trade is only worth it when continuity across sessions is the actual requirement.

## Licence, packaging and what to check before you commit

The project is MIT licensed, stated in both the LICENSE file and the Cargo.toml workspace package section, and package.json carries the same identifier. MIT is permissive and imposes no copyleft obligation on your own code. The repository also includes a THIRD_PARTY_NOTICES.md, which is where you would look for the licences of bundled dependencies, and that matters more than usual here because the Dockerfile notes that fastembed and ONNX Runtime are compiled in. If you redistribute the container image, those notices are the file to read. Nothing here is legal advice; check the notices yourself if redistribution is part of your plan.

Upgrade cost is the open question. With releases landing on consecutive days and no documented migration procedure in the README, the practical approach is to pin a specific image tag rather than tracking latest, and to read CHANGELOG.md before moving. The compose example uses the latest tag, which is convenient for a first look and risky for anything you depend on.

Before adopting, verify three things: that your target platform is macOS or that you accept the experimental label on Linux and Windows; that the /data volume on your host has room for the memory and knowledge stores you intend to build; and that the specific capability you need, whether that is the Obsidian binding, the Feishu workspace, or the browser control, appears in the docs/ directory rather than only in the README capability table.

## Conclusion

Adopt Hope Agent if you want a local-first desktop agent whose memory, goals and workflows survive across sessions, and you are willing to run a fast-moving project that ships releases almost daily. Do not adopt it if you need a stable API surface, a documented upgrade path, or a Windows-first desktop experience, since the README marks Windows and Linux as experimental. Before committing, verify the current release notes for breaking changes, confirm where your data directory lives, and check that the memory and workflow features you need are documented rather than only listed in the capability table.

## FAQ

### What is Hope Agent?

Hope Agent is a cross-device desktop AI assistant built in Rust with a Tauri 2 shell and a React frontend. The README describes it as local-first and desktop-first, with persistent memory, goal-driven execution and dynamic multi-agent workflows, and it can also run headless as a server.

### What is Hope AI used for?

The README positions it for long-running personal work: holding a goal across sessions, organising projects and tasks, maintaining a Markdown knowledge space, and generating design artifacts. It also supports browser and computer control under an approval layer.

### How do I install Hope Agent on a server?

The repository provides a docker-compose.yml that pulls ghcr.io/shiwenwen/hope-agent:latest and binds to 127.0.0.1:8420 by default. After starting the stack, run docker compose exec hope-agent hope-agent server token show to print the generated owner token, then enter it once in the browser.

### Which platforms does Hope Agent support?

The README badges mark macOS as supported, with Linux and Windows labelled experimental. The Docker path targets Debian trixie for both build and runtime because of a glibc requirement from the prebuilt ONNX Runtime binaries used for embeddings.

### What licence does Hope Agent use?

The LICENSE file, the Cargo.toml workspace package section and package.json all state MIT. The repository also includes THIRD_PARTY_NOTICES.md, which is relevant because the container image compiles in dependencies such as ONNX Runtime.

## Sources

- [Issues](https://github.com/shiwenwen/hope-agent/issues)
- [License: MIT](https://github.com/shiwenwen/hope-agent/blob/main/LICENSE)
- [README](https://github.com/shiwenwen/hope-agent/blob/main/README.md)
- [Releases](https://github.com/shiwenwen/hope-agent/releases)
- [shiwenwen/hope-agent on GitHub](https://github.com/shiwenwen/hope-agent)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shiwenwen-hope-agent