---
title: OSS Quick Start
description: Scaffold a ggui agentic app with `@ggui-ai/create-agentic-app` and run it locally — no account, no cloud, no ggui API key.
---

:::note[This is the OSS / self-hosted path]
This quickstart runs entirely on your own machine. **No account, no cloud, no API key.**

Want the managed ggui cloud (`mcp.ggui.ai`, coming soon) instead? See the [Hosted Quick Start](/getting-started/).
:::

Scaffold a complete ggui agentic app and run it locally — your agent, the ggui MCP server, a sample MCP server, and a web client — in one `npx`.

```
agent ── MCP ──→ ggui serve ──→ MCP-Apps resource ui://ggui/render/<id>
```

## Prerequisites

- **Node.js** 20+
- **pnpm**, **npm**, or **bun** — any recent package manager.
- An MCP-capable agent runtime (Claude Desktop, Claude Code, Cursor, or anything that reads `.mcp.json`).
- No account, no API key. Everything is local.

## Step 1: Scaffold a project

```bash
npx @ggui-ai/create-agentic-app my-app
cd my-app
pnpm install         # or: npm install / bun install
```

`@ggui-ai/create-agentic-app` scaffolds a small monorepo from an official template (`claude-agent-sdk` / `openai-agents-sdk` / `google-adk`): `servers/ggui/` (the ggui MCP server config), `servers/agent/` (your agent), `servers/mcps/todo/` (a sample MCP server), and `apps/web/` (a web client). See [`@ggui-ai/create-agentic-app`](https://www.npmjs.com/package/@ggui-ai/create-agentic-app) for the template list.

## Step 2: Boot the server

Set an LLM key in `.env.local` at the project root (any one — the boot probe walks `anthropic` → `openai` → `google` → `openrouter`):

```bash
# .env.local
ANTHROPIC_API_KEY=sk-ant-...
```

```bash
pnpm dev
```

`pnpm dev` boots the whole project together — the ggui MCP server (`ggui serve` from [`@ggui-ai/cli`](https://www.npmjs.com/package/@ggui-ai/cli), embedding `@ggui-ai/mcp-server`), your agent, the sample MCP server, and the web client. The ggui server (`servers/ggui`) defaults to `http://127.0.0.1:6781`:

- **MCP endpoint:** `http://127.0.0.1:6781/mcp`
- **WebSocket (live channel):** `ws://127.0.0.1:6781/ws`
- **Operator console:** `http://127.0.0.1:6781/`

Granular scripts (`dev:ggui`, `dev:agent`, `dev:mcps`, `dev:web`, `dev:stop`) run the pieces individually — see the scaffold's `README`.

:::tip[Local dev auth]
The scaffold's dev mode accepts any non-empty bearer (the `"Bearer dev"` in Step 3 below) as `builder` — fine on `127.0.0.1`, **never expose it to the open internet**. Switch to [pairing](/self-hosted/pairing/) when you tunnel out.
:::

:::tip[WebSocket URL differs by deployment]

- **Self-hosted / OSS (this guide):** `ws://127.0.0.1:6781/ws` — or `wss://<your-server>/ws` once you put TLS in front.
- **Hosted ggui (coming soon):** `wss://mcp.ggui.ai/ws` — handled for you. See the [Hosted Quick Start](/getting-started/).
  :::

## Step 3: Point an agent runtime at the local MCP

Add this entry to the scaffold's existing `.mcp.json` (it already contains a `ggui-dev` helper server):

```json
{
  "mcpServers": {
    "ggui": {
      "url": "http://127.0.0.1:6781/mcp",
      "headers": { "Authorization": "Bearer dev" }
    }
  }
}
```

Claude Desktop, Claude Code, Cursor, and any runtime that reads `.mcp.json` will discover the agent-facing tool catalogue — `ggui_handshake` / `ggui_render` / `ggui_update` / `ggui_emit` / `ggui_consume`, plus discovery tools (`ggui_get_session`, `ggui_list_sessions`, `ggui_list_gadgets`, `ggui_list_themes`, blueprint search/render).

The flow is **`handshake` → `render`**, with `ggui_update` to mutate props on a delivered render. Write a system prompt that tells the LLM when to render UIs — the [Examples](/examples/claude-agent/) section has working recipes per framework.

## What works today

- ✅ **Local server + wsToken-gated WebSocket subscribe → ack** work end-to-end — the iframe receives `wsUrl`/`wsToken` on the `ai.ggui/render` slice. Render plumbing is production-shaped, not a mock.
- ✅ **`handshake` → `render`** delivers an MCP-Apps resource (`ui://ggui/render/<id>`) that an MCP-Apps host mounts.
- ✅ **Component generation is wired via BYOK.** Export `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `OPENROUTER_API_KEY`) before `ggui serve` and `ggui_render` runs the real `@ggui-ai/ui-gen` pipeline (blueprint match → synth). Without any key, `ggui_render` returns a "Connect Claude" card pointing at the local `/settings` page rather than failing.
- ✅ **Per-app theming.** The scaffold's `servers/ggui/ggui.json` sets `theme: {preset: 'indigo', mode: 'dark'}`; agents can list presets via `ggui_list_themes` and override per render with `ggui_render({themeId})`.
- 🔒 **Default auth is pair-minted.** `/mcp` rejects bearers that weren't issued by the pairing flow. Pass `--dev-allow-all` to accept any non-empty bearer as `builder` (safe only on `127.0.0.1`), or swap in a real `AuthAdapter` via `createGguiServer({ auth })` before exposing the server beyond localhost.

## What this is not

- **Not a hosted service.** No ggui cloud account, no billing, no managed dashboards. For those, see the [Hosted Quick Start](/getting-started/) (coming soon).
- **Not a managed billing surface.** Generation runs on YOUR provider key (BYOK) — every `ggui_render` bills the provider directly. The hosted ggui cloud (coming soon) will bundle credit-metered billing and managed keys; this OSS path runs on your own provider key today.

## Vocabulary

- **Tool** — an agent-side action exposed over MCP (`ggui_render`, `ggui_handshake`, …).
- **Gadget** — a renderer-side capability surfaced inside the viewer (formerly `clientLibraries`).
- **Blueprint** — a cached component recipe matched before generation runs.

Full definitions: [Glossary](/glossary/).

## Just the bare MCP server

The scaffold orchestrates everything through `pnpm dev`. If you only want the OSS MCP server — no agent or web supervision — run [`ggui serve`](/cli/serve/) against a `ggui.json` directly (the same `ggui serve` the scaffold's `servers/ggui` runs):

```bash
# = ggui serve --mcp-only --dev-allow-all --port 6781
pnpm --filter ./servers/ggui start
```

Working from a monorepo clone rather than the published packages? Build the workspace copies first:

```bash
pnpm --filter @ggui-ai/cli build
node packages/ggui-cli/dist/cli.js serve --mcp-only
```

## What's next

- **[MCP Protocol Reference](/api/mcp-protocol/)** — wire format and tool catalogue (same on OSS and hosted).
- **[WebSocket Protocol](/api/websocket-protocol/)** — live-channel envelopes (`ActionEnvelope`, `StreamEnvelope`).
- **[Examples](/examples/claude-agent/)** — MCP-config-only integrations with system-prompt recipes (Claude, OpenAI, Gemini, OpenClaw, generic MCP).
- **[Hosted Quick Start](/getting-started/)** — managed generation and dashboards on ggui cloud (coming soon).
- **[GitHub repo](https://github.com/ggui-ai/ggui)** — source, issue tracker, full monorepo walkthrough.