ggui dev

ggui dev is the developer-facing inner loop. It loads ggui.ui.json blueprint manifests, serves the local registry + dev hub at 127.0.0.1:6780, and (with --agent <entry>) supervises a local agent runtime in the same shell. Distinct from ggui serve, the production-shaped self-host counterpart.

Quick start

ggui dev

Binds 127.0.0.1:6780, indexes any ggui.ui.json blueprints declared in ggui.json#blueprints.include, and auto-opens the dev hub in your browser.

To iterate against a local agent runtime in the same shell:

ggui dev --agent ./agent.ts

What you get

Port 6780 hosts the local blueprint registry + dev hub. The dev server exposes:

Path	What it serves
/hub	The dev dashboard (no auth — same-origin XHRs embed the bearer for everything else).
/hub/preview?ui=<id>	Iframe-mountable preview shell for one indexed blueprint.
/health	Liveness probe (no auth).
/uis, /uis/:id, /uis/:id/bundle	Discovered ggui.ui.json blueprints (Bearer auth).
/events	Server-sent events for live reload (Bearer auth).
/runtime/status, /runtime/events	Mounted when --agent <entry> is set (Bearer auth).

All non-/hub endpoints require Authorization: Bearer <token>. The token is taken from GGUI_DEV_TOKEN if set; otherwise a random one is generated and printed (with an export hint) on the boot banner.

ggui dev also sets GGUI_MODE=dev in the process env. The dev stack itself does not run an MCP server — that’s ggui serve’s job — but a supervised --agent that composes @ggui-ai/mcp-server inherits the env and mounts its own /devtools/* console namespace.

vs ggui serve

Concern	ggui dev	ggui serve
Audience	Developer iterating on UIs	Operator running a self-hosted instance
Default port	6780	6781
Default mode	GGUI_MODE=dev (mounts /devtools/*)	Production-shaped (no devtools)
Agent supervision	Opt-in via --agent <entry>	Default-on, sourced from ggui.json#agent.entry
Tunnel	Opt-in via --tunnel (provider seam; none bundled)	Bring your own (cloudflared etc.) + set --public-base-url
Auth posture	Loopback bind + single bearer token (GGUI_DEV_TOKEN)	Strict-auth pairing by default; opt-down via --dev-allow-all / --public-demo

Both can run side-by-side without colliding (different ports).

Flags

ggui dev [options]

Flag	Default	Purpose
--port <n>	6780	Bind port. 0 = OS-assigned.
--host <addr>	127.0.0.1	Bind host. Loopback only by default.
--no-serve	off	Load + discover and exit without binding. Useful for one-shot manifest validation / discovery dry-run.
--no-open	off	Skip auto-opening the browser at the hub URL. Implied by non-TTY stdout, BROWSER=none, or CI=1.
--agent <entry>	none	Supervise a local agent runtime. See Agent supervision for extension routing.
--tunnel	off	Opt into managed mode — open a managed tunnel above the local stack and print the remote URL. See Managed mode.

Agent supervision

--agent <entry> points at the agent file you’re iterating on. Extension routing decides how it’s spawned:

Extension	Spawn	Notes
.js, .mjs, .cjs	node <entry>	Plain Node
.ts, .tsx, .mts	node --import=tsx <entry>	tsx must be resolvable in your project (pnpm add -D tsx)

The dev-stack picks the agent’s port and forwards it via PORT env unless --tunnel is also set, in which case the CLI pre-allocates a free port and hands it down so the tunnel can forward inbound traffic to it.

Bad --agent paths fail before the socket binds — the CLI validates the command mapping and exits 1 with a remediation hint.

Managed mode tunnel

With --tunnel, once the local stack is listening ggui dev asks a TunnelProvider to open a managed tunnel above the host and prints the remote URL beside the local hub URL. The dev loop runs unchanged whether the tunnel resolves or not.

Provider discovery reads GGUI_TUNNEL_PROVIDER — a module specifier exporting createTunnelProvider(). No provider is bundled; without the env var the banner prints tunnel skipped: no tunnel provider configured and local dev runs unchanged. Real providers (cloudflared bindings, ngrok) plug into this seam without changing the CLI surface.

For a known-working public URL today, run cloudflared tunnel --url http://localhost:6780 (or your provider of choice) in a sibling shell, then point claude.ai or your MCP client at the printed URL. For the production-shaped equivalent on ggui serve, see ggui serve → Recommended setups.

Common workflows

Iterate on a blueprint manifest:

ggui dev
# edit packages/<your-app>/ggui.ui.json
# refresh the hub — the registry re-indexes on every load

Iterate on an agent + blueprints together:

ggui dev --agent ./agent.ts
# edit agent.ts → the supervised runtime restarts on file change (when the runtime supports it)
# edit ggui.ui.json → the registry re-indexes

Run a second ggui dev alongside the first (6780 is taken):

ggui dev --port 0
# 0 = OS-assigned; the actual port prints in the boot banner.
# Pass `--port 6790` (or any free integer) if you need a stable URL.

Validate manifests without binding a socket:

ggui dev --no-serve
# loads + discovers + exits non-zero on any malformed ggui.ui.json
# good in CI for catching manifest regressions

See also

• ggui CLI overview — the full command surface.
• ggui serve — production-shaped self-host counterpart.
• OSS Quick Start — the bootstrap walkthrough.
• Glossary — gadget / tool / blueprint definitions.