# HugAgentOS: A Self-Hosted Enterprise Agent Platform with Ontology-Grounded Reasoning and Approval Gating

> HugAgentOS is an open-source, self-hosted AgentOS from ZJU-REAL that treats domain ontology as a control plane for agent reasoning and actions. The Community Edition ships with agentic chat, private knowledge-base RAG, MCP tools, Agent Skills, sandboxed code execution, long-term memory, and a data canvas in one deployable workspace.

**ZJU-REAL/HugAgentOS** — HugAgentOS: The Self-Evolving AgentOS for Ontology-Grounded Trustworthy Reasoning

- Repository: https://github.com/ZJU-REAL/HugAgentOS
- Stars: 1,118 · Forks: 66
- Language: Python
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/zju-real-hugagentos

## What HugAgentOS Is and Who It Is For

HugAgentOS is an enterprise-grade AgentOS built by the ZJU-REAL research group at Zhejiang University. It provides a self-hosted workspace where AI agents can retrieve knowledge, work with files, run code, and carry real tasks through to completion. The README frames the goal as placing the context, execution capability, and artifact management an agent needs on a single path, with a domain ontology that acts as a machine-executable control plane.

The target user is an enterprise team or a self-hosting developer who needs a private, model-agnostic agent workspace. The Community Edition is designed for personal use with a single user or small team; it uses SQLite and in-process state in the one-command install profile. The Docker Compose path adds PostgreSQL, Redis, and isolated sandboxes for production-like deployments. Both paths run the same core features; the Docker Compose path is recommended when you need database durability, isolated sandbox execution, and persistent file storage across server restarts.

The platform is model-agnostic. The README describes connecting cloud or local models through a model-service configuration in the admin panel under Settings → System → Model services, without locking the application to a single vendor. The .env.example configures BRAND_PRODUCT_NAME and BRAND_ORG_NAME for white-labeling, though the README notes that the license requires retaining the Powered-by identifier.

The Community Edition repository is generated from the upstream main repository for each release. This means the source you clone is a sanitized distribution, not a fork you can contribute code back to directly.

## Two Install Paths: One-Command and Docker Compose

HugAgentOS provides two install paths. The first requires Python 3.11+, Node.js 20+, Git, and curl. No Docker, PostgreSQL, or Redis is needed:

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

The installer fetches the source into ~/.hugagent/source, creates an isolated Python environment, builds the web application, runs first-run setup, and opens http://127.0.0.1:3001. To start it again later:

```bash
~/.hugagent/venv/bin/hugagent
```

The second path uses Docker Compose and provides PostgreSQL, Redis, an isolated sandbox, and persistent volumes:

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

The Docker Compose path opens at http://localhost:3002. Both paths require connecting a model under Settings → System → Model services after first sign-in. The README warns that the initial account and password are both admin and must be changed on first sign-in.

## Core Capabilities: RAG, MCP Tools, Sub-Agents, and Skills

The Community Edition covers the full agent loop: conversation with SSE streaming and ReAct orchestration, private knowledge-base RAG with document chunking and hybrid vector plus keyword retrieval, optional reranking, and per-user isolation. Sub-agents with distinct roles are reachable by automatic routing or an @ mention. The MCP tool ecosystem includes built-in web search, page fetch, knowledge retrieval, chart generation, report creation, batch runs, automation, and skill management.

Agent Skills extend the agent with standardized skill definitions and scripts. Built-in skills are available, and the README describes a skill marketplace as a future source. The README also describes a layered memory system covering user profile (L1, on by default), episodic memory (L2), and knowledge (L3). The L2 and L3 memory layers require enabling the mem0 profile in Docker Compose; the one-command install path uses only L1 by default.

The data canvas feature is listed as a Community Edition capability; the README does not describe it in detail beyond listing it as included. Plan mode is available alongside conversation mode, giving the agent a structured planning step before execution begins.

The admin panel covers system settings, model service configuration, knowledge base management, user management, and audit logs. Web search is configurable through the admin panel or through environment variables, supporting Tavily, Baidu, and LangSearch. The .env.example shows the INTERNET_SEARCH_ENGINE variable and the corresponding API key variables for each provider. The README notes that the database value takes priority over the environment variable when both are set.

## Ontology Trust Control Plane and Approval Gating

The ontology trust control plane is the feature that differentiates HugAgentOS from a general-purpose agent framework. The README describes it as treating domain ontology as a machine-executable control plane: governed concepts, relations, rules, and action contracts give the skill, memory, and orchestration engines a shared business vocabulary.

In practice, candidate agent plans pass deterministic rule checks, risk-tiered evidence review, and a gate before execution. A violating action returns with the rule, the evidence, and a correction suggestion; it is never waved through silently. Approvals, rejections, evidence, and outcomes are recorded and distilled into versioned ontology proposals that take effect only after human review and can be rolled back.

The README includes an important caveat: the ontology trust control plane is an enterprise target architecture being integrated in stages into the existing harness. It strengthens structured compliance and evidence-based review; it does not promise "zero hallucination" for free text.

## Self-Evolution and Desktop Application

HugAgentOS supports self-evolution with human approval. The README's demo video shows the same task run twice with audited self-evolution in between: memory, skills, and orchestration each settle after the first run, and each change takes effect only after the user approves it. This incremental approval model is designed to keep the system's evolution transparent and reversible. Failed attempts and rejected proposals are recorded as part of the audit trail rather than silently discarded.

Desktop releases are available on GitHub. The most recent is desktop-v1.0.2, released on 2026-09-11. Earlier releases include desktop-v1.0.1 on 2026-08-09 and desktop-v0.2.14 on 2026-08-04. The desktop application installs on top of the server-side components and provides a native interface for the same core functionality.

The environment configuration example in .env.example documents the full set of configuration keys including database URL, Redis URL, authentication mode, model service settings, storage type, sandbox provider, and memory configuration. The mem0-based L2 and L3 memory layers require enabling a separate compose profile. The sandbox provider defaults to script_runner for the one-command install; the Docker Compose path uses an isolated container.

## Limitations, Alternatives, and License

The Community Edition repository is generated from the upstream main repository for each release and is marked as generated. The README notes that changes to src/** should be reported through Issues or Discussions rather than pull requests. Pull requests for documentation and examples are welcome.

The README does not specify an SPDX license identifier in the repository metadata (listed as NOASSERTION). The .env.example and pyproject.toml reference MIT. Teams should review the LICENSE file directly before deploying in a commercial context.

The last push was on 2026-09-27, one day before publication date, indicating active development. The requirements.txt pins agentscope==2.0.0 as the agent orchestration backbone. The README notes this is a fixed version because the GitHub main branch of agentscope has diverged and is incompatible.

AnthropicCloud's Claude with Projects, or OpenAI's Assistants API with file search, are managed-service alternatives that provide similar RAG and tool-use capabilities without the infrastructure overhead. HugAgentOS's advantage is data sovereignty: all storage runs on your own infrastructure, and the approval gating adds a governed compliance layer that managed services do not provide out of the box.

## Conclusion

HugAgentOS is a strong choice for teams that need a self-hosted, privacy-preserving agent workspace with built-in RAG, code execution, and a governed approval gate for high-risk actions. The ontology trust control plane is an enterprise target under active integration rather than a finished product, so the current Community Edition is most reliable for the core chat, RAG, and MCP tool loop. Verify two things before deploying: that the initial admin/admin credentials are changed on first sign-in, and that the deployment listens only on 127.0.0.1 unless a firewall, HTTPS, and strong authentication are in place. The Community Edition has no self-registration.

## FAQ

### What is HugAgentOS and what makes it different from a standard RAG chatbot?

HugAgentOS is a self-hosted AgentOS that goes beyond RAG: it includes sandboxed code execution, MCP tool integration, sub-agents, Agent Skills, long-term memory, and an ontology trust control plane that gates high-risk actions through a human-review approval step. A standard RAG chatbot retrieves and answers; HugAgentOS plans, executes, and records evidence for each action.

### How do I install HugAgentOS for personal use?

Run the one-command installer: curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bash. It requires Python 3.11+, Node.js 20+, Git, and curl. No Docker is needed. After install, the app opens at http://127.0.0.1:3001. Change the default admin/admin credentials on first sign-in.

### What AI models does HugAgentOS support?

HugAgentOS is model-agnostic. It connects to cloud or local models through a model-service configuration in the admin panel under Settings → System → Model services. The requirements.txt includes litellm for providers not natively supported by agentscope, google-genai for Gemini, and ollama for local Ollama models.

## Sources

- [Issues](https://github.com/ZJU-REAL/HugAgentOS/issues)
- [README](https://github.com/ZJU-REAL/HugAgentOS/blob/main/README.md)
- [Releases](https://github.com/ZJU-REAL/HugAgentOS/releases)
- [ZJU-REAL/HugAgentOS on GitHub](https://github.com/ZJU-REAL/HugAgentOS)

---

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