ZJU-REAL/HugAgentOS

HugAgentOS – Enterprise‑grade Agent Operating System

What it is – HugAgentOS is an open‑source, self‑hosted platform that lets you run AI agents that can retrieve information, manipulate files, execute code, and carry out end‑to‑end tasks. It is built around a domain ontology that acts as a control plane, letting the system enforce business rules, trace decisions, and manage permissions.

Key capabilities

Feature	What you get
Chat & planning	Real‑time SSE streaming, ReAct‑style tool orchestration, plan‑mode execution with citations and resumable runs.
Private RAG	Document chunking, hybrid vector‑keyword retrieval, optional reranking, per‑user isolation.
Sub‑agents	Personal “assistant” agents with distinct roles, reachable via routing or @ mentions.
MCP tool ecosystem	Built‑in web search, page fetch, knowledge retrieval, batch runs, automation, and a skill marketplace.
Agent Skills	Extend the core agent with reusable skill definitions written in Python/TS.
Automation / batch	Schedule natural‑language tasks; run a process over spreadsheets, Word docs, or file lists.
Group chat bots	Connect to Feishu, DingTalk, WeCom so the agent can read and reply in team channels.
Sandboxed execution	Code runs in a subprocess or lightweight container, producing charts, reports, web pages, etc.
Three‑layer memory	Profile stored in relational DB, optional Milvus vector memory, optional Neo4j graph memory.
Personal evolution	Changes to memory, skills or ontology are versioned, require human approval, and can be rolled back.
Workspace & data canvas	Projects, folders, artifact centre, and an in‑conversation data editor.

How you run it

• One‑command installer (Linux/macOS/WSL2) – pulls the repo, creates a virtual‑env, builds the React front‑end and starts the service on 127.0.0.1:3001. Uses SQLite and an in‑process sandbox – ideal for personal use.
• Docker‑Compose – spins up PostgreSQL, Redis, optional Milvus/Neo4j, and a sandbox container for production‑grade isolation and persistence. Accessible at http://localhost:3002.

Both approaches require an OpenAI‑compatible or locally hosted LLM; the UI lets you configure the model under Settings → System → Model services.

Architecture at a glance

• Agent runtime – built on AgentScope 2.0, ReAct, and the Model Context Protocol (MCP).
• Backend – FastAPI + SQLAlchemy + Alembic (Python).
• Frontend – React 19 + TypeScript + Vite + Ant Design.
• State & storage – SQLite or PostgreSQL, optional Redis, Milvus, Neo4j, or mem0 for vector/graph memory.
• Deployment – single‑binary installer, Docker Compose, or custom Nginx‑fronted deployment.

Why it matters

• Model‑agnostic – swap cloud or on‑prem LLMs without code changes.
• Trustworthy execution – plans are checked against ontology‑defined rules; violations are reported with evidence instead of being silently executed.
• Traceability – every approval, rejection, and outcome is recorded, enabling versioned ontology updates and rollback.
• Data stays on‑prem – all databases and file stores run on your infrastructure.

Editions

• Community Edition (this repo) – full personal‑agent stack, open source under Apache 2.0 with extra attribution terms.
• Enterprise Edition – adds multi‑tenant governance, SSO, organization‑wide skill review, persistent sandboxes, billing, and collaboration tools (source not included here).

Getting started

# one‑command install (Linux/macOS/WSL2)
curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bash
# later start
~/.hugagent/venv/bin/hugagent

Or with Docker Compose:

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

Documentation & community – English and Chinese guides cover introduction, quick‑start, deployment, architecture, ontology building, and module development. Contributions are welcomed via Issues, Discussions, or pull requests (documentation and examples only, core code is generated from the upstream repo).

---

All details are taken directly from the repository’s README; no external assumptions are added.