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 to src/** through an
Issue or Discussion. Pull requests for documentation and examples are
welcome. See CONTRIBUTING.md for details.
Choose the local installer for a personal trial or Docker Compose for a server-oriented, service-isolated deployment. Both methods require access to an OpenAI-compatible or local model.
Install the personal, single-machine profile on Linux, macOS, or WSL2. You
need Python 3.11 or later, Node.js 20 or later, Git, and curl. On Linux
platforms without a compatible prebuilt ripgrep wheel, you also need the
current stable Rust toolchain. You don't need Docker, PostgreSQL, or Redis.
curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bashThe installer clones HugAgentOS into ~/.hugagent/source, creates an isolated
Python environment, installs the dependencies, builds the web application, and
opens the first-run wizard. Follow the prompts to create an administrator and
connect an OpenAI-compatible or local model. HugAgentOS then opens at
http://127.0.0.1:3001.
A fresh data directory creates exactly one local administrator. The initial
username and password are both admin, and the password must be changed on the
first sign-in. CE does not provide self-service registration.
Warning
The one-click server listens on 127.0.0.1 by default. If you need remote
access to a server, run
hugagent serve --host 0.0.0.0 --port 3001 --no-browser, and configure a
strong administrator password, a firewall, and HTTPS first. Don't expose the
service directly on an untrusted network.
Start HugAgentOS again at any time with this command:
~/.hugagent/venv/bin/hugagentNote
The one-command profile is designed for personal trials and development. It uses SQLite, in-process state, and a local subprocess sandbox. For long-running servers or production-style isolation, use the Docker Compose deployment guide.
For installer options, capability boundaries, and troubleshooting, read the no-Docker installation guide.
Use Docker Compose when you need PostgreSQL, Redis, an isolated sandbox, durable service volumes, or a long-running server deployment. You need Git, Docker Engine or Docker Desktop, and Docker Compose v2.
git clone https://github.com/ZJU-REAL/HugAgentOS.git
cd HugAgentOS
cp .env.example .env
mkdir -p data/storage
docker compose up -d --buildOpen http://localhost:3002. The initial account and
password are both admin; change the password at the first sign-in. Then open
Settings → System Administration → Model Services to connect an
OpenAI-compatible or local model.
Check the service status with docker compose ps. To stop the stack without
deleting its data, run docker compose down. For profiles, persistence,
production configuration, and rebuild workflows, read the
Docker Compose deployment guide.
HugAgentOS isn't another wrapper around a chat box. It puts the context, execution environment, and artifact management an agent needs into one task flow.
|
🔌 Bring your model Connect cloud or local models through one provider layer without locking the application to a single vendor. |
🛠️ Take action ReAct orchestration combines MCP, skills, and a sandbox to search, analyze, create files, and call external capabilities. |
|
🧠 Retain context Private knowledge bases and layered memory provide context across files and conversations. |
🏠 Own your data Run the application, databases, and file storage on infrastructure you control. |
HugAgentOS uses domain ontology as an executable control plane, not only as a knowledge store. Controlled concepts, relationships, invariants, action contracts, roles, and permissions give the skill, memory, and orchestration engines one shared business language.
|
🧭 Shared semantic ground Align domain intent, skills, tools, memory, and agent roles against one versioned set of concepts and relationships. |
🏗️ Build-time governance Validate skills, tools, and sub-agents as they are created or imported, and assemble capabilities through consistent Action contracts. |
|
🛡️ Policy-gated execution Turn a candidate plan into action through deterministic rule checks, risk-based evidence review, and gated execution. Violations return with the rule, evidence, and repair guidance instead of silently proceeding. |
🔎 Traceable, governed evolution Record approvals, rejections, evidence, and outcomes. Enforcement events become versioned ontology proposals that require human review and remain reversible. |
Note
The ontology trust plane is a target enterprise architecture being integrated incrementally on top of the current Harness. It strengthens structured compliance and evidence-backed review; it doesn't claim to eliminate every free-text hallucination.
Community Edition covers the complete personal-agent loop from conversation and execution to retention and reuse. Optional infrastructure stays optional during the first run.
|
💬 Agentic chat and Plan Mode SSE streaming, ReAct tool orchestration, deep thinking, Plan Mode, traceable citations, and resumable streams. |
📚 Private knowledge-base RAG Document ingestion and chunking, hybrid vector and keyword retrieval, optional reranking, and private knowledge isolation. |
|
🤝 Personal sub-agents Create agents with focused roles, then collaborate through automatic routing or @ mentions.
|
🔧 MCP tool ecosystem Built-in web search, page fetching, knowledge retrieval, charts, reports, batch jobs, automation, and skill management. |
|
🧩 Agent Skills Extend agents with structured instructions and scripts through bundled skills, a skill marketplace, and personal skills. |
⚙️ Automation and batch execution Create scheduled tasks in natural language or apply one workflow across spreadsheets, Word documents, and file lists. |
|
🧪 Sandbox and artifacts Run code in a local subprocess or lightweight container sandbox, then create charts, reports, Office files, websites, and data-canvas artifacts. |
🧠 Three-tier personal memory Store the L1 personal profile in the relational database, with optional Milvus vector memory and Neo4j graph memory. |
|
🗂️ Personal workspace Organize long-running work with projects, folders, favorites, shared conversations, and an artifact center. |
📊 Data canvas Inspect and edit structured data inside the conversation so the analysis and final result stay 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, gateway, and persistent-sandbox 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, batch execution, and a personal data canvas | Organization billing, usage reports, and canvas collaboration |
| Lightweight sandbox and local file storage | Persistent sandboxes, 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.
Future Community Edition development will focus on a connected workspace, efficient model orchestration, and a broader extension ecosystem.
- Cloud/local switching and cross-client continuity. Enable seamless switching between cloud-hosted and local runtimes. A single server deployment will connect supported clients and synchronize conversations, agents, skills, files, and task state so work can move between interfaces without losing context.
- Adaptive model routing with Mixture of Agents (MoA). Select, switch, or combine models based on task complexity, modality, latency, and cost. Simple tasks can use lightweight models, while demanding tasks can escalate to stronger or specialized models, maintaining quality while reducing unnecessary token usage.
- A richer extensibility ecosystem. Expand the catalog of built-in and community agents, skills, MCP servers and tools, and plugins. Improve the supporting workflows for discovery, installation, updates, compatibility, quality review, and security review so reusable capabilities are easier to build and share.
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.
- 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.
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.