--- title: Introduction description: ggui is an open, MCP-native protocol for AI agents to render interactive UI on demand. GGUI Preview — self-hosted via `ggui serve`. --- import { LinkButton } from "@astrojs/starlight/components"; :::note[GGUI Preview 0.1.0] This is the **GGUI Preview** release. The protocol is a pre-1.0 draft (`draft-2026-06-12`) and may change. The open-source **self-hosted** path is fully available today — run the whole protocol locally with [`ggui serve`](/cli/serve/), no account required. The managed cloud (`mcp.ggui.ai` and the `console.ggui.ai` dashboard) is **coming soon** and is not part of this preview. ::: **ggui** is an open protocol that lets AI agents render interactive UI on the fly. Your agent describes what it needs in natural language; ggui compiles a typed component and returns it as an MCP-Apps resource (`ui://ggui/render/`) that your host mounts. The UI reports back typed events the next time your agent calls `ggui_consume`. You run the whole protocol yourself with **`ggui serve`** — no account, no cloud, no API key. A managed hosted endpoint that speaks the same wire is coming after the preview. Quickstart — local in 5 minutes How ggui works Reading as an LLM? :::note[ggui vs guuey] **ggui** (this site) is the open protocol — source at [github.com/ggui-ai/ggui](https://github.com/ggui-ai/ggui). **guuey** is a separate SaaS agent-hosting platform built on the same protocol. (The hosted `mcp.ggui.ai` endpoint is the ggui-side managed deployment, coming after the preview.) ::: ## Choose your path ### Agent Builder — wire ggui into an MCP server Start with the [Quickstart](/oss-quickstart/) (5 min, local). Then read the [MCP protocol reference](/api/mcp-protocol/), browse the [Cookbook](/cookbook/feedback-form/), or copy a worked [example agent](/examples/claude-agent/). ### Host — connect a client to your server [Connect Claude Desktop](/clients/claude-desktop/) to a `ggui serve` you run yourself. [Other MCP hosts](/clients/connect-other-hosts/) use the same self-hosted endpoint with their own config shape. ### Operator — self-host the stack [`ggui serve`](/cli/serve/) is the local deployment guide. [Reference deploys](/self-hosted/reference-deploys/) covers Docker, Fly.io, and Render. The [Self-hosted Registry](/sdk/self-hosted-registry/) is the artifact layer for private gadgets and blueprints. ### Agentic App Builder — make your SaaS agent-drivable If you ship a SaaS or webapp and want agents to drive it without rewriting the frontend, see [Agentic App Builders](/agentic-app-builders/). ### LLM agent reading docs Every page is also raw markdown at the same slug. Start with [`/llms.txt`](/llms.txt) (index, per the [llms.txt convention](https://llmstxt.org/)), `/llms-full.txt` (single-file dump of the whole site), or `/llms-small.txt` (compact variant). See [the LLM-agent track](/agents/) for the full machine-readable surface. ## How ggui works A typical exchange is four moments — **handshake → render → interact → consume**. See [How ggui works](/how-it-works/) for the full walk-through with code. ## Key concepts A few terms recur across the docs: - **GguiSession** — one rendered UI, minted by `ggui_render` (*render* is the verb; the object it creates is a GguiSession). Each GguiSession carries a stable `sessionId`. - **Contract** — the typed agreement between agent and renderer for one GguiSession. - **Tool** — an agent-side action (`ggui_render`, `ggui_consume`, …) — the MCP surface. - **Gadget** — a renderer-side capability (Leaflet map, Stripe Checkout, …) the LLM can compose with. - **Blueprint** — a cached recipe — a UI promoted from one-shot to "use this exact screen next time." → [Glossary](/glossary/) for everything else. ## What's on this site - **[How ggui works](/how-it-works/)** — narrative walk-through for builders - **[Quickstart](/oss-quickstart/)** — zero to a running local server in 5 minutes - **Protocol** — [Overview](/protocol/overview/) · [Envelopes](/protocol/envelopes/) · [Bootstrap](/protocol/bootstrap-handshake/) · [Conformance](/protocol/conformance/) · [Version policy](/protocol/version-policy/) - **API** — [MCP](/api/mcp-protocol/) · [WebSocket](/api/websocket-protocol/) · [MCP Apps](/api/mcp-apps/) · [OAuth (self-hosted)](/api/oauth/) · [Ops MCP](/api/ops-mcp/) · [Rate limits](/api/rate-limits/) - **SDK** — [React](/sdk/react/) · [Gadgets](/sdk/gadgets/) · [Marketplace](/sdk/marketplace/) · [Self-hosted Registry](/sdk/self-hosted-registry/) - **CLI** — [Overview](/cli/) · [`ggui dev`](/cli/dev/) · [`ggui serve`](/cli/serve/) - **Connect a host** — [Claude Desktop](/clients/claude-desktop/) · [Other MCP hosts](/clients/connect-other-hosts/) - **Self-hosted** — [Pair a client app](/self-hosted/pairing/) · [Reference deploys](/self-hosted/reference-deploys/) - **Cookbook** — [Feedback form](/cookbook/feedback-form/) · [Multi-step wizard](/cookbook/multi-step-wizard/) · [Real-time dashboard](/cookbook/real-time-dashboard/) · [Auth-gated UI](/cookbook/auth-gated-ui/) · [Theming](/cookbook/custom-theming/) · [Error handling](/cookbook/error-handling/) · [Chat](/cookbook/chat-own-storage/) · [Testing](/cookbook/testing/) - **Architecture** — [Overview](/architecture/overview/) · [Agent backend](/architecture/agent-backend/) · [Audience routes](/architecture/audience-routes/) · [MCP services](/architecture/mcp-services/) · [Event System](/architecture/event-system/) · [UI Generator](/architecture/ui-generator/) - **Design System** — [Design Tokens](/design/tokens/) - **Examples** — [Claude Agent](/examples/claude-agent/) · [OpenAI](/examples/openai-agent/) · [Gemini](/examples/gemini-agent/) · [OpenClaw](/examples/openclaw-agent/) · [Generic MCP](/examples/generic-mcp/) - **Glossary** — [terminology reference](/glossary/) - **Troubleshooting** — [common errors and what they mean](/troubleshooting/)