| --- |
| title: README |
| emoji: ⚡ |
| colorFrom: yellow |
| colorTo: indigo |
| sdk: docker |
| pinned: false |
| --- |
| |
| --- |
|
|
| 🧠 |
|
|
| ------------- |
|
|
| <p align="center"> |
| <br /> |
| <strong>Build AI agents that do real work — not just answer questions.</strong> |
| <br /> |
| <br /> |
| <span> |
| Agent Runtime · Visual Workflows · Model Routing · Knowledge Retrieval · Self-hosted AI Workspace |
| </span> |
| <br /> |
| <br /> |
| <a href="#why-zgi">Why ZGI</a> · |
| <a href="#what-you-can-build">What You Can Build</a> · |
| <a href="#quick-start">Quick Start</a> · |
| <a href="#architecture">Architecture</a> · |
| <a href="#development">Development</a> · |
| <a href="#license">License</a> |
| </p> |
| |
| <p align="center"> |
| <img src="https://img.shields.io/badge/Agent_Runtime-ZGI-blue?style=for-the-badge" /> |
| <img src="https://img.shields.io/badge/Self--hostable-Docker-indigo?style=for-the-badge" /> |
| <img src="https://img.shields.io/badge/Workflows-Visual_Orchestration-purple?style=for-the-badge" /> |
| <img src="https://img.shields.io/badge/License-Source_Available-black?style=for-the-badge" /> |
| </p> |
|
|
| --- |
|
|
| ## Why ZGI |
|
|
| **ZGI is a source-available AI application platform for teams building internal AI tools, agent apps, and workflow-driven automation.** |
|
|
| Most AI tools start with a chat box. |
| ZGI starts with a more practical question: |
|
|
| > What does an AI application need in order to run inside a real organization? |
|
|
| That means more than prompts and model calls. |
| It needs controlled model access, workspace knowledge, database permissions, reusable skills, workflow orchestration, runtime isolation, observability, and deployment control. |
|
|
| ZGI brings these capabilities into one self-hostable workspace: |
|
|
| * **Agent applications** for assistants, copilots, and internal AI tools |
| * **Visual workflows** for multi-step automation and business processes |
| * **Model routing** for providers, credentials, pricing, and policy control |
| * **Knowledge retrieval** for approved workspace context |
| * **Runtime skills** for files, charts, reports, calculations, scheduling, and tool execution |
| * **Self-hosted services** for teams that want infrastructure control |
|
|
| In short: **ZGI helps teams move from AI demos to AI systems.** |
|
|
| --- |
|
|
| ## What You Can Build |
|
|
| | Capability | What it enables | |
| | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | |
| | **Agent Apps** | Publish AI assistants with instructions, model settings, memory, file upload, knowledge, and reusable skills. | |
| | **Visual Workflows** | Build multi-step processes with LLM calls, API requests, JSON parsing, branches, loops, approvals, notifications, retrieval, and code execution. | |
| | **Model Operations** | Manage providers, channels, credentials, default models, pricing metadata, and policy controls in one place. | |
| | **Knowledge & Data Access** | Bind agents to approved knowledge bases, documents, datasets, and database tables instead of exposing broad workspace access. | |
| | **Runtime Skills** | Give agents reusable capabilities for file generation, charts, reports, scheduling, calculations, database actions, and workflow calls. | |
| | **Self-hosted Runtime** | Run the console, API, sandbox, plugin runner, PostgreSQL, Redis, and optional knowledge services in your own environment. | |
| | **Starter Templates** | Explore built-in agent and workflow templates in English and Simplified Chinese. | |
|
|
| --- |
|
|
| ## Platform Overview |
|
|
| ```text |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ ZGI Console │ |
| │ Agent Apps · Workflows · Knowledge · Models · Skills │ |
| └─────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ ZGI API │ |
| │ Workspace Control · Runtime Orchestration · Policies │ |
| └─────────────────────────────────────────────────────────────┘ |
| │ |
| ┌───────────────────┼───────────────────┐ |
| ▼ ▼ ▼ |
| ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ |
| │ PostgreSQL │ │ Redis │ │ Sandbox │ |
| │ Metadata Store │ │ Runtime Cache │ │ Tool Execution │ |
| └─────────────────┘ └─────────────────┘ └─────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────┐ |
| │ Plugin Runner │ |
| │ Reusable Skills │ |
| └─────────────────┘ |
| |
| Optional knowledge services: |
| Weaviate · Neo4j |
| ``` |
|
|
| --- |
|
|
| ## Quick Start |
|
|
| Start ZGI locally with Docker: |
|
|
| ```bash |
| ./dev/start-docker --full |
| ``` |
|
|
| Then open: |
|
|
| ```text |
| http://localhost:2679 |
| ``` |
|
|
| On first launch, create the first administrator account. |
| ZGI does **not** ship with a default admin account. |
|
|
| ### Docker Profiles |
|
|
| | Command | Services | |
| | -------------------------------- | -------------------------------------- | |
| | `./dev/start-docker --core` | Core product preview | |
| | `./dev/start-docker --runtime` | Core stack plus Sandbox and Runner | |
| | `./dev/start-docker --knowledge` | Core stack plus knowledge dependencies | |
| | `./dev/start-docker --full` | Full stack, same as the default | |
|
|
| Stop the stack: |
|
|
| ```bash |
| make docker-down |
| ``` |
|
|
| View logs: |
|
|
| ```bash |
| make docker-logs |
| ``` |
|
|
| --- |
|
|
| ## Repository Layout |
|
|
| ```text |
| . |
| ├── api/ Go backend service |
| ├── web/ Next.js web console |
| ├── sandbox/ Isolated execution service |
| ├── runner/ Plugin execution service |
| ├── docker/ Product-level Docker Compose assets |
| ├── dev/ Local development scripts |
| ├── scripts/ Maintenance scripts |
| ├── docs/ Public documentation and assets |
| ├── Makefile Common local entry points |
| └── README.md |
| ``` |
|
|
| --- |
|
|
| ## Development |
|
|
| Install the local toolchain first: |
|
|
| * Docker and Docker Compose |
| * Make |
| * Go |
| * Node.js |
| * pnpm |
|
|
| The web app uses: |
|
|
| ```text |
| pnpm@10.12.1 |
| ``` |
|
|
| Prepare dependencies: |
|
|
| ```bash |
| make setup |
| ``` |
|
|
| Start shared infrastructure: |
|
|
| ```bash |
| make dev-docker |
| ``` |
|
|
| Run the backend and frontend from source in separate terminals: |
|
|
| ```bash |
| make dev-api |
| make dev-web |
| ``` |
|
|
| --- |
|
|
| ## Documentation |
|
|
| Read the product documentation: |
|
|
| ```text |
| https://docs.zgi.ai |
| ``` |
|
|
| Repository-local README files are kept for development and contribution notes. |
|
|
| Useful references: |
|
|
| * Product-level Docker notes: `docker/README.md` |
| * Release process: `docs/release-process.md` |
| * Script skill input files: `docs/script-skill-input-files.md` |
| * Web app notes: `web/README.md` |
| * Backend service docs: `api/` |
|
|
| --- |
|
|
| ## Who ZGI Is For |
|
|
| ZGI is designed for teams that want to: |
|
|
| * Build internal AI tools without scattering prompts, keys, and workflows everywhere |
| * Keep model access, knowledge retrieval, and runtime permissions under control |
| * Turn AI assistants into repeatable business processes |
| * Connect agents to approved workspace data, databases, and tools |
| * Run AI application infrastructure inside their own environment |
| * Move from prototype demos to production-ready AI workflows |
|
|
| --- |
|
|
| ## License |
|
|
| ZGI source code is available under the **ZGI Community License**, based on Apache License 2.0 with additional conditions. |
|
|
| ZGI is free for personal, research, educational, and internal organizational use. |
|
|
| Hosted multi-tenant services, white-label distribution, and removal of official ZGI branding require a commercial license. |
|
|
| This license is **not an OSI-approved open source license**. |
| See `LICENSE` for details. |
|
|
| The Apache License 2.0 text referenced by the ZGI Community License is included in `LICENSE-APACHE`. |
|
|
| --- |
|
|
| <p align="center"> |
| <strong>ZGI — From AI chat to AI runtime.</strong> |
| <br /> |
| Build agents, workflows, and internal AI systems with control. |
| </p> |
|
|
|
|
