Skip to content
ggui

Hosted Quick Start

Build a working ggui integration against hosted Guuey in under 5 minutes. Your agent will push a feedback form to a user, wait for their response, and process the submitted data.

Your Agent → hosted Guuey → Generated Form UI → User fills it → Agent gets the data

Prerequisites

Section titled “Prerequisites”
  • Node.js 18+
  • A Guuey account at platform.guuey.com (hosted path only — the OSS ggui serve path needs no account)

Step 1: Create an App and Get Your API Key

Section titled “Step 1: Create an App and Get Your API Key”
  1. Go to platform.guuey.com/apps and sign in
  2. Click “New App” (or go to /apps/new) and give it a name (e.g., “My First Agent”)
  3. Submit the form. An API-key dialog opens immediately with both your App ID and API key (starts with ggui_sk_)
  4. Click Copy to copy the API key, then save the App ID shown next to it — you’ll need both

Keep your API key secret. Never commit it to source control. The key is shown once — if you lose it, you can rotate to a new one from Workspace Settings → API Keys.

Step 2: Install the SDK

Section titled “Step 2: Install the SDK”
Terminal window
npm install @ggui-ai/mcp-client

Or with other package managers:

Terminal window
pnpm add @ggui-ai/mcp-client
yarn add @ggui-ai/mcp-client

Step 3: Write Your Agent

Section titled “Step 3: Write Your Agent”

Create a file called agent.ts:

import { GguiClient } from "@ggui-ai/mcp-client";


// Initialize the client
const ggui = new GguiClient({
  apiKey: process.env.GGUI_API_KEY!,
  appId: process.env.GGUI_APP_ID!,
});


async function main() {
  // 1. Push a UI — ggui generates a feedback form
  console.log("Generating feedback form...");
  const { sessionId, url } = await ggui.push({
    story: {
      intent: "Collect product feedback",
      prompt: "Show a feedback form with a 1-5 star rating and a comments text area",
    },
  });


  console.log(`Share this URL with your user: ${url}`);


  // 2. Wait for the user to submit
  console.log("Waiting for user to submit...");
  const events = await ggui.waitForCompletion(sessionId, {
    pollInterval: 2000, // Check every 2 seconds
    maxWait: 300_000, // Give up after 5 minutes
  });


  // 3. Process the response
  const submitEvent = events.find((e) => e.type === "data:submit");
  if (submitEvent) {
    // `data:submit` envelopes carry `{ action, data, tool? }`. `action`
    // matches the action id from the UI's contract (e.g. "submit"); the
    // form fields you want are on `data`.
    console.log("User submitted:", submitEvent.payload.data);
  } else {
    console.log("No submission received (user may have timed out)");
  }


  // 4. Clean up
  await ggui.close(sessionId);
  console.log("Done!");
}


main().catch(console.error);

Step 4: Run It

Section titled “Step 4: Run It”

Set your environment variables and run:

Terminal window
export GGUI_API_KEY="ggui_sk_..."
export GGUI_APP_ID="app_..."
npx tsx agent.ts

You’ll see output like:

Generating feedback form...
Share this URL with your user: https://render.guuey.com/abc123
Waiting for user to submit...

Open the URL in your browser — you’ll see a generated feedback form. Fill it out and submit. Back in your terminal:

User submitted: { rating: 4, comments: "Works great!" }
Done!

Step 5: Embed in React (Optional)

Section titled “Step 5: Embed in React (Optional)”

Want to render the ggui UI inside your own React app instead of using the render URL? Install the React SDK:

Terminal window
npm install @ggui-ai/react

Wrap your app in GguiProvider and use GguiSession:

import { GguiProvider, GguiSession, StackItemRenderer } from "@ggui-ai/react";


function App({ sessionId, stackItem }) {
  return (
    <GguiProvider appId="app_..." wsEndpoint="wss://ws.guuey.com">
      <GguiSession
        sessionId={sessionId}
        onInteraction={(envelope) => {
          // `envelope` is the canonical `ActionEnvelope`
          // (`{ sessionId, type: 'interaction:*', payload, ... }`).
          console.log("User interaction:", envelope);
        }}
        onError={(error) => console.error("Session error:", error)}
      >
        {({ connectionStatus }) => (
          <div>
            {connectionStatus !== "connected" && <p>Connecting...</p>}
            <StackItemRenderer stackItem={stackItem} />
          </div>
        )}
      </GguiSession>
    </GguiProvider>
  );
}

The generated UI renders live inside your app, with real-time updates as the user interacts.

What Just Happened?

Section titled “What Just Happened?”
  1. Your agent called ggui.push() with a natural language prompt
  2. ggui’s UI Builder generated a React component from the prompt (using AI)
  3. The render URL served the generated UI to the user’s browser
  4. The user filled out the form and submitted it
  5. Your agent polled ggui.consume() (via waitForCompletion()) and received the submission data
Agent                      ggui                       Browser
  │                          │                           │
  │── push("feedback form") →│                           │
  │                          │── generate UI ──→ compile  │
  │← { sessionId, url } ────│                           │
  │                          │                           │
  │                          │←── user opens URL ────────│
  │                          │──── rendered form ───────→│
  │                          │                           │
  │── consume(sessionId) ──→│                           │
  │                          │←── data:submit ──────────│
  │← { events } ────────────│                           │
  │                          │                           │
  │── close(sessionId) ────→│                           │

Next Steps

Section titled “Next Steps”
  • MCP Client SDK — Full API reference for the GguiClient class
  • React SDK — Embed ggui UIs in your React app
  • Examples — See OpenClaw, Claude, OpenAI, and Gemini integrations
  • Cookbook — Common patterns with code samples
  • Troubleshooting — Common issues and solutions