---
title: README
emoji: โก
colorFrom: yellow
colorTo: indigo
sdk: docker
pinned: false
---
---
๐ง
-------------
Build AI agents that do real work โ not just answer questions.
Agent Runtime ยท Visual Workflows ยท Model Routing ยท Knowledge Retrieval ยท Self-hosted AI Workspace
Why ZGI ยท
What You Can Build ยท
Quick Start ยท
Architecture ยท
Development ยท
License
---
## 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`.
---
ZGI โ From AI chat to AI runtime.
Build agents, workflows, and internal AI systems with control.