HugAgentOS: the open-source Agent Harness that runs 24/7

Hand it your question, then close your laptop —
the agent keeps working in the cloud and tells you when it's done.

English · 简体中文

Website · Try HugAgentOS online

Models keep getting stronger, but getting an agent to actually finish the job depends on the layer around the model: run lifecycle, context assembly, tools and sandboxes, human approvals, memory, and failure recovery. That layer is the agent harness.

HugAgentOS is an open-source, self-hosted agent harness built around the durable agent: your request runs in the cloud, not in your browser or on your computer. Close the tab, shut the laptop or go offline, and the task keeps moving; you can also hand off tasks and get results in the IM app you use. On top of that, HugAgentOS provides an always-on Personal Agent and runs in two forms — HugAgent Cloud (on your server) and HugAgent Local (on your desktop) — which can also be combined.

[!NOTE] This Community repository is generated from the upstream main repository for each release and is marked generated. Report changes to src/** through an Issue or Discussion. Pull requests for documentation and examples are welcome. See CONTRIBUTING.md for details.

At a glance

Demo

A 60-second tour: the same task run twice, with audited self-evolution in between — memory, skills and orchestration each settled, and each taking effect only after you approve it.

https://github.com/user-attachments/assets/635c5b35-10c0-47b9-a6f1-c73df9510e90

⏱️ Durable agent: close the laptop, the work goes on

Once you hand a task to HugAgentOS, it runs in cloud services and sandboxes — your device is just a window onto it. Leave whenever you like, or come back on another device; you always see the same progress and results.

09:00  In Feishu, tell the agent: "Research pricing for competitors A, B and C, put it in a table and write a comparison report"
09:01  The agent replies "Started"; the task runs in a cloud sandbox → you close the laptop and go to a meeting
10:40  It needs to send an email: an approval reminder arrives in Feishu, and you approve it on the web from your phone
11:30  The report arrives in the same Feishu chat
11:35  Reply "Add D as well" → the same task picks it up, no restart

Why it keeps going

• Runs in the cloud, not on your device: background tasks, schedules and heartbeats run on the server, and working files live in a dedicated persistent sandbox. Closing the page doesn't stop anything, and any device can pick up the live progress.
• Survives server failures: progress is saved to the database step by step and executed by leased workers. If a process or machine dies, another instance takes over from the last saved progress instead of silently dropping the task.
• Never repeats risky actions: emails, writes to external systems and other operations record their intent and outcome. On recovery, anything that may or may not have happened is not redone automatically — you confirm "executed" or "not executed".
• Runs until it's done: long tasks and the autonomous loop have no total time limit or business turn cap; stall detection, failure circuit breakers and a hard backstop prevent runaways. Waiting for your approval or answer doesn't consume the execution budget.
• Change your mind mid-run: add requirements at any time and the agent takes them at its next step, with no cancel-and-restart.
• Finds you when it needs you: actions that need approval are approved on the web, with a reminder in IM; until you answer, the task waits instead of acting on its own.

[!IMPORTANT] Continuous cloud operation relies on PostgreSQL, Redis and OpenSandbox — deploy HugAgent Cloud with Docker Compose. The one-command install uses SQLite and in-process state and is meant for trials and development.

🤖 Personal Agent: an agent that is always on

Personal Agent is built on the durable harness above: one conversation, one persistent identity, one permanent cloud computer. You just say what you need; it decides whether to answer right away or start a background task, and reports back when the work is done.

Personal Agent is off by default in the Community Edition. In a HugAgent Cloud deployment, set PERSONAL_AGENT_ENABLED=true and enable the personal-agent Compose profile. See the Personal Agent guide.

☁️ HugAgent Cloud and 💻 HugAgent Local

The same harness, placed wherever your data and compute should live.

• HugAgent Cloud is the complete durable harness, for work that must stay online, be reachable from any device and connect to IM channels. Each Docker sandbox uses a separate bridge with the trusted backend and controller; sandbox host ports are not published and peer sandboxes cannot reach each other's execd.
• HugAgent Local ships its own private Python runtime and services, so no Python, Docker or database install is needed. It can run fully offline with local models; once a local project is bound, Bash and file tools work directly in the project's real directory. A failed upgrade rolls back to the previous version and data backup.
• Hybrid mode uses one cloud account: cloud conversations are stored in the cloud, while only local projects' conversations, files and execution stay on the machine. This is also how Personal Agent "connects this computer" so an always-on cloud agent can operate your desktop.

See Desktop local mode and Local project workspace.

🧬 Self-evolution: better with real work, audited at every step

HugAgentOS does not make the agent start from zero every time — and does not let it quietly learn the wrong things.

• Learning procedures from trajectories: the post-response memory pipeline keeps outcome-verified trajectories such as "failure → user correction → success" as reusable procedural memory instead of facts that go stale; stable procedures can be compiled further into skills.
• Three memory layers: L1 personal profile, L2 vector procedural memory (Milvus, optional) and L3 relationship graph (Neo4j, optional). Writes go through a durable outbox so crash replays never add duplicates, and a sanitizer filters credentials.
• Approved one by one, reversible: evolution proposals for memory and skills appear as cards and only take effect after you confirm them; you can switch it off at any time.
• Dreaming for Personal Agent: a daily job consolidates logs into MEMORY.md / USER.md, with DREAMS.md recording sources, deduplication and conflicts; only what you explicitly asked it to remember is promoted automatically.

🧰 More harness capabilities

Quick start

Every option needs an OpenAI-compatible or local model. The initial account and password are both admin and must be changed on first sign-in; the Community Edition has no self-registration.

HugAgent Cloud: Docker Compose (recommended for 24/7)

Install Git, Docker, and Compose v2 first.

git clone https://github.com/ZJU-REAL/HugAgentOS.git
cd HugAgentOS
cp .env.example .env
mkdir -p data/storage
docker compose build backend
docker compose up -d --build

Open http://localhost:3002, sign in, and connect a model under Settings → System administration → Model services. See the Docker Compose guide for persistence and production settings, and Deploy Personal Agent to enable it.

HugAgent Local: desktop client

Download the installer for your platform from Releases and choose "Local only", "Cloud only" or "Local + cloud" on first launch. The full offline package bundles its runtime, so nothing else needs to be installed.

Developer trial: one-command install (Linux / macOS / WSL2)

Requires Python 3.11+, Node.js 20+, Git and curl. No Docker, PostgreSQL or Redis needed.

curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bash

The installer clones the source into ~/.hugagent/source, creates an isolated Python environment, builds the web app and runs the first-time setup wizard, then opens http://127.0.0.1:3001. Start it again later with ~/.hugagent/venv/bin/hugagent-server.

[!WARNING] It listens on 127.0.0.1 only by default. If you really need remote access, use hugagent-server serve --host 0.0.0.0 --port 3001 --no-browser, and set up a strong password, a firewall and HTTPS first. Don't expose it directly on an untrusted network.

The one-command install uses SQLite, in-process state and a local subprocess sandbox, which suits trials and development. See the quick install guide for options and troubleshooting.

Architecture

HugAgentOS separates user channels, agent workflows, reusable capability engines, data governance, and infrastructure into clear layers. Durable runs, leases and recovery run through the execution path, while security and platform governance span the complete stack.

[!NOTE] The diagram shows the complete HugAgentOS product architecture. Some governance, collaboration, and gateway capabilities are available only in Enterprise Edition.

Technology stack

See the architecture overview for the full request lifecycle, container topology, and design decisions.

Community and Enterprise editions

Community Edition lets an individual run the complete harness and Personal Agent. Enterprise Edition adds the governance, collaboration, and delivery capabilities needed to operate the same experience across an organization. Enterprise-only source is physically absent from the Community tree.

See the edition overview for the complete feature boundary and upgrade path.

Documentation

Start from document/README.md to browse every guide.

Roadmap

1. Seamless Cloud/Local switching across clients — building on today's hybrid mode, one server deployment serving multiple clients, keeping conversations, agents, skills, files and task state in sync.
2. Adaptive model routing based on Mixture of Agents — select or combine models by task complexity, modality, latency and cost: light models for simple work, stronger ones only when the task warrants it.
3. A richer extension ecosystem — more built-in and community agents, skills, MCP servers and plugins, with better discovery, installation, updates, and quality and security review.

Contributing

We welcome bug reports, feature proposals, documentation improvements, and reproducible patches. Read CONTRIBUTING.md before you start so you understand the boundary between generated and directly editable content. By participating, you agree to follow our bilingual Community Code of Conduct.

• Include reproduction steps, expected behavior, actual behavior, and your environment in bug reports.
• Explain the concrete use case and problem when proposing a feature.
• Keep English and Chinese documentation aligned with the Community and Enterprise edition boundary.

Don't open a public Issue for a security vulnerability. Follow SECURITY.md to report it through a private channel.

License

HugAgentOS Community Edition is licensed under Apache License 2.0 with supplementary terms. The terms restrict operating the software as a competing multi-tenant SaaS offering and require the UI's Powered-by attribution to remain visible. LICENSE and NOTICE define the complete rights and obligations for internal use, modification, and distribution.