HugAgentOS: The Self-Evolving AgentOS for Ontology-Grounded Trustworthy Reasoning
Python
616
374 commits
updated Oct 18, 2026
HugAgentOS: The Enterprise AgentOS for Ontology-Grounded Trustworthy Reasoning
The open-source, self-hosted foundation for enterprise AI agents
Give models the context and tools to retrieve knowledge, work with files, run code, and carry real tasks through to completion.
Website · Try HugAgentOS online
HugAgentOS is an enterprise-grade AgentOS that treats domain ontology as a control plane for agent reasoning, decisions, and actions. Its open-source Community Edition combines agentic chat, private knowledge-base RAG, sub-agents, MCP tools, Agent Skills, sandboxed execution, long-term memory, automation, and a data canvas in one self-hosted workspace.
[!NOTE] This Community repository is generated from the upstream main repository for each release and is marked
generated. Report changes tosrc/**through an Issue or Discussion. Pull requests for documentation and examples are welcome. See CONTRIBUTING.md for details.
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
Use the one-command install to try it out, or Docker Compose for a long-running
service with isolation. Either way you need 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.
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 fetches the source into ~/.hugagent/source, creates an isolated
Python environment, builds the web application and walks you through first-run
setup; it then opens http://127.0.0.1:3001. Start it
again later with ~/.hugagent/venv/bin/hugagent.
[!WARNING] The installation listens on
127.0.0.1only. If you genuinely need remote access, usehugagent serve --host 0.0.0.0 --port 3001 --no-browser, and set a strong password, a firewall and HTTPS first. Do not expose it on an untrusted network.
This path uses SQLite, in-process state and a local subprocess sandbox, which suits personal use and development. Options and troubleshooting are in the one-command install guide.
Use this when you need PostgreSQL, Redis, an isolated sandbox and persistent volumes. Requires Git, Docker and Compose v2.
git clone https://github.com/ZJU-REAL/HugAgentOS.git
cd HugAgentOS
python3 scripts/configure-ce-docker.py
docker build -f docker/Dockerfile.opensandbox -t hugagent-opensandbox-custom:latest .
docker compose up -d --build
Docker CE uses OpenSandbox by default. Initialization creates private controller credentials and absolute host paths. It refuses to overwrite an existing .env. Local installation keeps subprocess execution.
Open http://localhost:3002, then connect a model under Settings → System → Model services. Profiles, persistence and production configuration are covered in the Docker Compose deployment guide.
The point is not another chat wrapper. It is putting the context, the execution capability, and the artifact management an agent needs to finish real work on a single path — and raising the domain ontology from a knowledge base to a machine-executable control plane, so that governed concepts, relations, rules and action contracts give the skill, memory and orchestration engines one shared business vocabulary.
|
🔌 Model-agnostic Connect cloud or local models through one model-service configuration, without locking the application to a single vendor. |
🛠️ Actually does the work ReAct orchestrates MCP servers, skills and sandboxes, so the model can search, analyse, produce files and call external capabilities. |
|
🧠 Knowledge and memory Private knowledge bases and layered memory supply long-term context across files and conversations. |
🏠 Your data stays yours Application, database and file storage all run on your own infrastructure. |
|
🛡️ Gated, trustworthy execution Candidate plans pass deterministic rule checks, risk-tiered evidence review and a gate. A violating action returns with the rule, the evidence and a correction — it is never waved through silently. |
🔎 Traceable evolution Approvals, rejections, evidence and outcomes are all recorded, distilled into versioned ontology proposals that take effect only after human review, and can be rolled back. |
[!NOTE] The ontology trust control plane is an enterprise target architecture being integrated into the existing harness in stages. It strengthens structured compliance and evidence-based review; it does not promise "zero hallucination" for free text.
The Community Edition covers the full loop for a personal agent — conversation, execution, consolidation and reuse. Optional components are enabled as needed.
| Capability | What it gives you |
|---|---|
| 💬 Conversation and plan mode | SSE streaming, ReAct tool orchestration, deep thinking, plan mode, citations, resumable runs |
| 📚 Private knowledge base RAG | Document chunking, hybrid vector and keyword retrieval, optional reranking, per-user isolation |
| 🤝 Personal sub-agents | Sub-agents with distinct roles, reached by automatic routing or an @ mention |
| 🔧 MCP tool ecosystem | Built-in web search, page fetch, knowledge retrieval, batch runs, automation, skill management |
| 🧩 Agent Skills | Extend the agent with standardised skill definitions and scripts — built-in, marketplace and personal |
| ⚙️ Automation and batch runs | Create scheduled tasks in natural language; run one process across an Excel sheet, a Word file or a file list |
| 💬 Group chat channels | Feishu / DingTalk / WeCom bots, with optional group listening and history retrieval so the agent can see the conversation around it |
| 🧪 Sandbox and artifacts | Run code locally or in an OpenSandbox container, producing charts, reports, Office files, web pages and data canvases |
| 🧠 Three-layer personal memory | L1 profile in the relational store; optional Milvus vector memory and Neo4j graph memory |
| 🧬 Personal evolution | Settle memory and skills out of your real work, each approved individually before it applies to you, and switchable off |
| 🗂️ Personal workspace | Projects, folders, favourites, conversation sharing and an artifact center |
| 📊 Data canvas | Inspect and edit structured data inside the conversation, keeping analysis and result in one workspace |
HugAgentOS separates user channels, agent workflows, reusable capability engines, ontology contracts, data governance, and infrastructure into clear layers. Action contracts connect the ontology layer to planning, validation, and gated execution, 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.
The project combines mature, replaceable open-source components behind clear service boundaries.
| Layer | Main technologies |
|---|---|
| Agent runtime | AgentScope 2.0, ReAct, Model Context Protocol |
| Backend | Python, FastAPI, SQLAlchemy, Alembic |
| Frontend | React 19, TypeScript, Vite, Zustand, Ant Design |
| Data and state | SQLite or PostgreSQL 15, in-process state or Redis 7, local file storage |
| Optional memory | Milvus 2.4, Neo4j 5 Community, mem0 |
| Deployment | One-command local installer, Docker Compose, Nginx |
See the architecture overview for the full request lifecycle, container topology, and design decisions.
Community Edition gives an individual a complete agent workspace. 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.
| Community Edition | Enterprise Edition adds |
|---|---|
| Agentic chat, Plan Mode, and personal sub-agents | Teams, organization agents, and permission matrices |
| 8 general MCP tools, personal skills, and a skill marketplace | Industry data tools, organization governance, and skill review |
| Private knowledge bases and three-tier personal memory | Public knowledge administration and memory auditing |
| Automation, and a personal data canvas | Organization billing, usage reports, and canvas collaboration |
| OpenSandbox sessions, snapshots, and local file storage | Team workspace mounts, Cube, cloud storage, and offline delivery |
| Local accounts and branding with Powered-by attribution | SSO, compliance auditing, and full white-labeling |
See the edition overview for the complete feature boundary and upgrade path.
The repository includes complete English and Chinese documentation for operators, users, and contributors, and you can read it offline.
| Goal | English | 中文文档 |
|---|---|---|
| Understand the product | Introduction | 产品简介 |
| Run it in 10 minutes | Quick start | 快速开始 |
| Configure a deployment | Deployment | 部署指南 |
| Explore the system design | Architecture | 架构总览 |
| Build a domain ontology | Domain ontology quickstart | 快速构建领域本体 |
| Learn MCP, skills, memory, and sandboxing | Modules | 功能模块 |
| Build backend or frontend features | Development | 开发指南 |
Start from document/README.md to browse every guide.
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.
Don't open a public Issue for a security vulnerability. Follow SECURITY.md to report it through a private channel.
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.
Each Docker sandbox uses a separate bridge with the trusted backend and controller. Sandbox host ports are not published; peer sandboxes cannot access each other's execd. Use the bundled custom controller image.
174 followers · starred Jul 2026
20 followers · starred Sep 2026
HugAgentOS: The Self-Evolving AgentOS for Ontology-Grounded Trustworthy Reasoning
Python
616
374 commits
updated Oct 18, 2026
HugAgentOS: The Enterprise AgentOS for Ontology-Grounded Trustworthy Reasoning
The open-source, self-hosted foundation for enterprise AI agents
Give models the context and tools to retrieve knowledge, work with files, run code, and carry real tasks through to completion.
Website · Try HugAgentOS online
HugAgentOS is an enterprise-grade AgentOS that treats domain ontology as a control plane for agent reasoning, decisions, and actions. Its open-source Community Edition combines agentic chat, private knowledge-base RAG, sub-agents, MCP tools, Agent Skills, sandboxed execution, long-term memory, automation, and a data canvas in one self-hosted workspace.
[!NOTE] This Community repository is generated from the upstream main repository for each release and is marked
generated. Report changes tosrc/**through an Issue or Discussion. Pull requests for documentation and examples are welcome. See CONTRIBUTING.md for details.
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
Use the one-command install to try it out, or Docker Compose for a long-running
service with isolation. Either way you need 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.
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 fetches the source into ~/.hugagent/source, creates an isolated
Python environment, builds the web application and walks you through first-run
setup; it then opens http://127.0.0.1:3001. Start it
again later with ~/.hugagent/venv/bin/hugagent.
[!WARNING] The installation listens on
127.0.0.1only. If you genuinely need remote access, usehugagent serve --host 0.0.0.0 --port 3001 --no-browser, and set a strong password, a firewall and HTTPS first. Do not expose it on an untrusted network.
This path uses SQLite, in-process state and a local subprocess sandbox, which suits personal use and development. Options and troubleshooting are in the one-command install guide.
Use this when you need PostgreSQL, Redis, an isolated sandbox and persistent volumes. Requires Git, Docker and Compose v2.
git clone https://github.com/ZJU-REAL/HugAgentOS.git
cd HugAgentOS
python3 scripts/configure-ce-docker.py
docker build -f docker/Dockerfile.opensandbox -t hugagent-opensandbox-custom:latest .
docker compose up -d --build
Docker CE uses OpenSandbox by default. Initialization creates private controller credentials and absolute host paths. It refuses to overwrite an existing .env. Local installation keeps subprocess execution.
Open http://localhost:3002, then connect a model under Settings → System → Model services. Profiles, persistence and production configuration are covered in the Docker Compose deployment guide.
The point is not another chat wrapper. It is putting the context, the execution capability, and the artifact management an agent needs to finish real work on a single path — and raising the domain ontology from a knowledge base to a machine-executable control plane, so that governed concepts, relations, rules and action contracts give the skill, memory and orchestration engines one shared business vocabulary.
|
🔌 Model-agnostic Connect cloud or local models through one model-service configuration, without locking the application to a single vendor. |
🛠️ Actually does the work ReAct orchestrates MCP servers, skills and sandboxes, so the model can search, analyse, produce files and call external capabilities. |
|
🧠 Knowledge and memory Private knowledge bases and layered memory supply long-term context across files and conversations. |
🏠 Your data stays yours Application, database and file storage all run on your own infrastructure. |
|
🛡️ Gated, trustworthy execution Candidate plans pass deterministic rule checks, risk-tiered evidence review and a gate. A violating action returns with the rule, the evidence and a correction — it is never waved through silently. |
🔎 Traceable evolution Approvals, rejections, evidence and outcomes are all recorded, distilled into versioned ontology proposals that take effect only after human review, and can be rolled back. |
[!NOTE] The ontology trust control plane is an enterprise target architecture being integrated into the existing harness in stages. It strengthens structured compliance and evidence-based review; it does not promise "zero hallucination" for free text.
The Community Edition covers the full loop for a personal agent — conversation, execution, consolidation and reuse. Optional components are enabled as needed.
| Capability | What it gives you |
|---|---|
| 💬 Conversation and plan mode | SSE streaming, ReAct tool orchestration, deep thinking, plan mode, citations, resumable runs |
| 📚 Private knowledge base RAG | Document chunking, hybrid vector and keyword retrieval, optional reranking, per-user isolation |
| 🤝 Personal sub-agents | Sub-agents with distinct roles, reached by automatic routing or an @ mention |
| 🔧 MCP tool ecosystem | Built-in web search, page fetch, knowledge retrieval, batch runs, automation, skill management |
| 🧩 Agent Skills | Extend the agent with standardised skill definitions and scripts — built-in, marketplace and personal |
| ⚙️ Automation and batch runs | Create scheduled tasks in natural language; run one process across an Excel sheet, a Word file or a file list |
| 💬 Group chat channels | Feishu / DingTalk / WeCom bots, with optional group listening and history retrieval so the agent can see the conversation around it |
| 🧪 Sandbox and artifacts | Run code locally or in an OpenSandbox container, producing charts, reports, Office files, web pages and data canvases |
| 🧠 Three-layer personal memory | L1 profile in the relational store; optional Milvus vector memory and Neo4j graph memory |
| 🧬 Personal evolution | Settle memory and skills out of your real work, each approved individually before it applies to you, and switchable off |
| 🗂️ Personal workspace | Projects, folders, favourites, conversation sharing and an artifact center |
| 📊 Data canvas | Inspect and edit structured data inside the conversation, keeping analysis and result in one workspace |
HugAgentOS separates user channels, agent workflows, reusable capability engines, ontology contracts, data governance, and infrastructure into clear layers. Action contracts connect the ontology layer to planning, validation, and gated execution, 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.
The project combines mature, replaceable open-source components behind clear service boundaries.
| Layer | Main technologies |
|---|---|
| Agent runtime | AgentScope 2.0, ReAct, Model Context Protocol |
| Backend | Python, FastAPI, SQLAlchemy, Alembic |
| Frontend | React 19, TypeScript, Vite, Zustand, Ant Design |
| Data and state | SQLite or PostgreSQL 15, in-process state or Redis 7, local file storage |
| Optional memory | Milvus 2.4, Neo4j 5 Community, mem0 |
| Deployment | One-command local installer, Docker Compose, Nginx |
See the architecture overview for the full request lifecycle, container topology, and design decisions.
Community Edition gives an individual a complete agent workspace. 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.
| Community Edition | Enterprise Edition adds |
|---|---|
| Agentic chat, Plan Mode, and personal sub-agents | Teams, organization agents, and permission matrices |
| 8 general MCP tools, personal skills, and a skill marketplace | Industry data tools, organization governance, and skill review |
| Private knowledge bases and three-tier personal memory | Public knowledge administration and memory auditing |
| Automation, and a personal data canvas | Organization billing, usage reports, and canvas collaboration |
| OpenSandbox sessions, snapshots, and local file storage | Team workspace mounts, Cube, cloud storage, and offline delivery |
| Local accounts and branding with Powered-by attribution | SSO, compliance auditing, and full white-labeling |
See the edition overview for the complete feature boundary and upgrade path.
The repository includes complete English and Chinese documentation for operators, users, and contributors, and you can read it offline.
| Goal | English | 中文文档 |
|---|---|---|
| Understand the product | Introduction | 产品简介 |
| Run it in 10 minutes | Quick start | 快速开始 |
| Configure a deployment | Deployment | 部署指南 |
| Explore the system design | Architecture | 架构总览 |
| Build a domain ontology | Domain ontology quickstart | 快速构建领域本体 |
| Learn MCP, skills, memory, and sandboxing | Modules | 功能模块 |
| Build backend or frontend features | Development | 开发指南 |
Start from document/README.md to browse every guide.
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.
Don't open a public Issue for a security vulnerability. Follow SECURITY.md to report it through a private channel.
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.
Each Docker sandbox uses a separate bridge with the trusted backend and controller. Sandbox host ports are not published; peer sandboxes cannot access each other's execd. Use the bundled custom controller image.
174 followers · starred Jul 2026
20 followers · starred Sep 2026