` | `auto` (default): `GITHUB_REPOSITORY`/`GITHUB_SHA` when set, else `git remote get-url origin` + `git rev-parse HEAD`, path = cwd relative to the repo root. `none`: don’t record. `@[:]`: explicit. | | `--json` | Emit the response verbatim (see below). | | `--app-id ` | Target another app — e.g. one manifest applied to a staging and a production app. | ### The response, and the drift gate [Section titled “The response, and the drift gate”](#the-response-and-the-drift-gate) The `--json` response is the contract your pipeline gates on: ```json { "applied": true, "unchanged": false, "dryRun": false, "appId": "7365f90e-…", "buildNumber": 12, "status": "queued", "deployedContentHash": { "agentDef": "", "systemPrompt": "", "snapshot": "" }, "provenanceRecorded": true, "statusPath": "/v1/apps/7365f90e-…/deployments/12/status", "plan": { "snapshot": "changed", "config": [{ "field": "guestAccess", "current": null, "desired": false }] }, "convergedFields": ["guestAccess"], "shadowedDocFields": ["standalonePage"] } ``` `agentDef` and `systemPrompt` hash **your bytes verbatim** — compare them with `sha256sum guuey.json prompts/system.md` and fail the job on a mismatch (“green means deployed”). `snapshot` hashes the exact string persisted on the build row: the platform assembles it from your document (prompt inlined, the app’s generative-UI binding injected) in a canonical form, so identical inputs always produce the identical hash — that is what `unchanged` compares. `convergedFields` is on **every** response: the config fields the server actually diffed this call — every field present in the effective desired config, whether or not it produced a change (`plan.config` is always a subset), in a stable canonical order. Gate on it: a pipeline that asserts its declared blocks appear in `convergedFields` catches a silently dropped block immediately. Dropping one is easier than it sounds — if your request carries an explicit `config`, that config **replaces** the document-derived one wholesale (it is not merged field-by-field), so a block your document declares can quietly stop converging. When exactly that happens, `shadowedDocFields` names the document-declared fields your explicit `config` suppressed — a warning, never an error (the override is legitimate; gate on it or not, your choice), and omitted when empty. A field present in both with a *different value* is not a shadow — that is the override doing its job. `guuey agent apply` prints the echo as a `converged:` line and any shadow as a `!` warning. ## `guuey agent status` [Section titled “guuey agent status”](#guuey-agent-status) ```bash guuey agent status ``` ```plaintext App: 7365f90e-… Live: build #12 (live) · xs · deployed 2026-08-16T20:04:11.000Z managed from acme/agents@da49f6dcaabc (agents/helper) snapshot sha256 c7d4… Config: userAuthMode: "byo" userAuthConfig: {"issuerUrl":"https://id.example.com","audience":"console"} allowedDomains: ["https://console.example.com"] guestAccess: false ``` Add `--check` to also compare **this checkout** byte-exact against the live build (a dry-run reconcile behind the scenes): `✓ Checkout is in sync with build #12 (byte-exact).` (exit 0) or `✗ DRIFT — this checkout differs from build #12:` followed by the diff (exit 2). A build that was deployed outside agents-as-code (`guuey deploy`, the console) shows `no provenance`. `guuey deployments` lists every build (`--json` includes each build’s provenance and hash); `GET /v1/apps/:id/deployments/:n` serves provenance and hash per build. ## `guuey agent rollback --to ` [Section titled “guuey agent rollback --to \”](#guuey-agent-rollback---to-n) Re-serve a previous build’s **exact bytes** as a new build — no checkout, no rebuild, from anywhere with `--app-id` (why this can be byte-exact — immutable snapshots, row-driven serving — is explained in [Deployments & rollback](/concepts-deployments/)): ```bash guuey agent rollback --to 7 --wait ``` ```plaintext ✓ Rolled back — build #9 queued, re-serving build #7 byte-exact — bytes from acme/agents@1f0e2d3c4b5a (agents/helper). sha256 snapshot: c7d4… ``` The source is build #7’s persisted snapshot — the string its pod booted from — so the new build serves what served then, byte for byte, and its row keeps #7’s provenance (`guuey agent status` then reads `build #9 (live) (rolled back from #7)`, still `managed from acme/agents@…`). Every gate a fresh deploy passes runs again (schema, lints, tier and size ceilings, build caps). If the pinned bytes are already what is live, nothing is queued. Rollback **refuses rather than approximates**: a build whose stored snapshot would no longer re-serialize byte-identical (the platform’s canonical form moved since — a schema default, the app’s generative-UI binding), a code build, or a row without a snapshot answers `409 ROLLBACK_NOT_EXACT` with the way out (`guuey agent apply` from that commit). Rollback re-serves build material only — it never touches the app’s access policy; if the manifest at that commit declared a different `app.access`, apply from that commit instead. Flags: `--wait`, `--json`, `--app-id `; the wire is `POST /v1/apps/:id/reconcile/rollback { "buildNumber": 7 }` → `{ applied, unchanged, rolledBackFrom, buildNumber, deploymentId, status, contentHash, provenance, statusPath }`, callable with the same credentials as `apply`. ## The CI credential: an app service token [Section titled “The CI credential: an app service token”](#the-ci-credential-an-app-service-token) Do not put a personal login in CI. Mint an **app-scoped service token** once, as the app’s owner: ```bash guuey tokens create --label "github-actions" --app-id ``` The secret (`guuey_svc_…`) is printed **once**. It is bound to that one app, may only call the reconcile routes (`agent apply` / `agent status` / `agent rollback`) and read that app’s deployment history — no tier, no billing, no delete, no other apps, and `guuey deploy` refuses it. It never expires; `guuey tokens revoke ` is the kill switch. Store it as a CI secret and pass it through `GUUEY_API_KEY`. A personal key via `GUUEY_API_KEY` also works (full user authority, real expiry) — fine for a laptop, wrong for a pipeline. ### Workspace-owned apps: the CI credential is a workspace API key [Section titled “Workspace-owned apps: the CI credential is a workspace API key”](#workspace-owned-apps-the-ci-credential-is-a-workspace-api-key) An app owned by a **workspace** (a team) cannot mint a service token — a token bound to whichever member minted it would outlive that member’s seat. Its CI credential is a **workspace API key** (`guuey_wkz_…`), which authenticates as the workspace itself: a workspace admin creates it in the console at **Settings → Workspace → *your workspace* → API keys → Create key** (`/settings/workspaces//api-keys`); the secret is shown once. Store it as a CI secret and pass it the same way, through `GUUEY_API_KEY` — `guuey agent apply | status | rollback` and the raw reconcile routes accept it for every app that workspace owns. Its scope is fixed by the platform, not per key: the deploy plane (reconcile, deploy, deployment reads and status, env, logs, config, generative-UI asset push) — never app creation or deletion, listing, domains, slugs, branding, service-token or workspace-key management, or anything that needs a named member behind the call. Revoke it from the same console page. (No `guuey wkeys` CLI verb yet — creation is console-only.) ## GitHub Actions example [Section titled “GitHub Actions example”](#github-actions-example) Two jobs: a plan on every pull request, an apply on merge to `main`. The same manifest can target one app per environment with `--app-id`. ```yaml name: agent on: pull_request: paths: ["agents/helper/**"] push: branches: [main] paths: ["agents/helper/**"] env: GUUEY_API_URL: https://api.us-east-1.guuey.com/v1 GUUEY_API_KEY: ${{ secrets.GUUEY_SERVICE_TOKEN }} jobs: plan: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 22 } - run: npm install -g @guuey/cli - name: Plan (a diff is expected on a PR — exit 2 is the plan, only a real error fails) working-directory: agents/helper run: guuey agent apply --dry-run || test $? -eq 2 apply: if: github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 22 } - run: npm install -g @guuey/cli - name: Apply id: apply working-directory: agents/helper run: guuey agent apply --wait --json | tee reconcile.json - name: Drift gate — the bytes Guuey persisted are the bytes we reviewed working-directory: agents/helper run: | want_def=$(sha256sum guuey.json | cut -d' ' -f1) want_prompt=$(sha256sum prompts/system.md | cut -d' ' -f1) got_def=$(jq -r .deployedContentHash.agentDef reconcile.json) got_prompt=$(jq -r .deployedContentHash.systemPrompt reconcile.json) test "$want_def" = "$got_def" && test "$want_prompt" = "$got_prompt" ``` `GITHUB_REPOSITORY` and `GITHUB_SHA` are set by Actions, so provenance is recorded automatically; `guuey agent status` on the app then reads `managed from /@ (agents/helper)`. ## The API, if you’d rather not run the CLI [Section titled “The API, if you’d rather not run the CLI”](#the-api-if-youd-rather-not-run-the-cli) Everything above is one route: ```plaintext POST /v1/apps/:appId/reconcile Authorization: Bearer { "artifacts": { "guueyJson": "", "systemPrompt": "" }, "config": { … same fields as app.access, plus builtFor — optional; when absent, the document's app section is used }, "provenance": { "repo": "org/repo", "path": "agents/helper", "sha": "" }, "deploymentId": "", "size": "xs — optional pod size, same values as guuey deploy --size", "dryRun": false } GET /v1/apps/:appId/reconcile → { appId, live: { buildNumber, status, deploymentId, deployedAt, size, provenance, contentHash, rolledBackFrom } | null, config: { … } } POST /v1/apps/:appId/reconcile/rollback { "buildNumber": 7 } → { applied, unchanged, appId, rolledBackFrom, buildNumber, deploymentId, status, contentHash, provenance, statusPath } ``` Errors are always JSON `{"error": {"code", "message"}}`, and the call is idempotent, so retries are safe. While an app is on its [7-day trial](/plans-and-billing/), `GET /v1/apps/:id` carries `trial: { startedAt, endsAt, status }` (`null` once the app is off the trial); a deploy or reconcile against an expired, unpaid app answers `409 TRIAL_EXPIRED` — choosing a plan on the app resumes it, no redeploy needed. A `guuey.json` document must carry `"schema": "1"` at the root and only the documented sections — an unrecognized root key is rejected by name. ### Schema versions [Section titled “Schema versions”](#schema-versions) The root `schema` is a decimal string (`"1"` today), bumped only when the document shape changes in a way an older reader cannot interpret. The CLI and the platform compare against the **same** constant (`SUPPORTED_GUUEY_JSON_SCHEMA` in `@guuey/config`), and both refuse rather than guess: `guuey agent apply` (like `guuey deploy`) stops before any network call with `[SCHEMA_TOO_NEW]` and tells you to upgrade `@guuey/cli` when the document is newer than the CLI; the reconcile and deploy-trigger routes answer `400 SCHEMA_UNSUPPORTED` when a document is newer than the platform serves. An **older** schema is accepted only when a migration to the current one exists — none does yet, so today the rule is simply “equal, or refused”. A document that passes locally and gets `SCHEMA_UNSUPPORTED` from the API means your CLI is ahead of the platform; wait for the platform to catch up rather than downgrading the file. ## Not (yet) converged from the manifest [Section titled “Not (yet) converged from the manifest”](#not-yet-converged-from-the-manifest) Slug, custom domain, store listing, and branding have their own ceremonies (claiming, DNS verification, uploads) and stay on their commands for now. Tier and billing never move to CI. Workspace-owned apps cannot mint service tokens — use a workspace API key (above). # Drop-in chat UI > Mount @guuey/chat's and get the transcript UI guuey's own surfaces use — streaming, tools, generative-UI cards, every failure state designed. [`@guuey/chat`](https://www.npmjs.com/package/@guuey/chat) (MIT) is the default chat UI for guuey agents — the same transcript tier guuey’s own surfaces run: the embeddable widget, the console’s playground, and the Portal apps all render through this package. Mount it with your agent’s endpoint and you get a production chat surface; keep customizing until only the parts you care about are yours. The design bar it holds: **an agent transcript stays readable in every weird case** — a 40-second turn running a dozen tools, a generative view mounting mid-stream, a failed tool, a cold-started agent, a dropped connection. Each of those is a designed state, not an accident. A `ggui_render` refusal is a named state (as of `@guuey/chat` 0.18.1 with `@ggui-ai` 0.15.0): `@guuey/mcp-apps-host` parses the tool result’s `structuredContent` against the protocol’s render output schema into a typed refusal, and the row renders as **Not rendered** with the refusal’s `code` — every tool row carries a `refusal` field, `null` unless one parsed. Anything that isn’t a parsed refusal still takes the generic failed-tool path: the row shows ✕ and its expansion is the result’s `structuredContent` as a bounded JSON preview, with no card mounted. ```sh npm install @guuey/chat ``` ## Mount it in ten lines [Section titled “Mount it in ten lines”](#mount-it-in-ten-lines) ```tsx "use client"; import { GuueyChat } from "@guuey/chat/react"; import "@guuey/chat/styles.css"; export function AgentChat() { return ( ); } ``` Both values come from your deploy: the endpoint is printed by `guuey deploy` (and shown by `guuey apps get`), the app id by `guuey apps list`. Before your page goes to production, [allow its domain](/sdk/#allow-your-domain) and verify with `guuey apps check --origin` — same rules as any custom surface. ## What you get for free [Section titled “What you get for free”](#what-you-get-for-free) * **Streaming text** as sanitized markdown — raw HTML from the model is structurally unrepresentable in the rendering pipeline, not merely escaped. * **Tool activity as calm one-liners** — a running tool is a live status line; consecutive finished tools collapse into one expandable “Ran N tools” row; a tool that produces something visible (a generative-UI card, media, a prompt) always renders in place, never buried in a collapse. * **Generative-UI cards mount sandboxed** — agents using ggui render interactive views inline, in a locked-down iframe, with the negotiation states labeled (“no host answer” instead of a blank frame). * **Cold starts are narrated** — “Connecting…” escalates to “Getting ready…”, then “Still getting ready. The first reply can take a little longer.”, driven by the platform’s real turn lifecycle (as of `@guuey/chat` 0.31.0; earlier versions show “Starting your agent…”, then “Starting your agent… first load can take a minute”). * **Dropped connections recover themselves** — if a stream goes silent while the agent actually finished, the UI adopts the completed reply from persisted history instead of freezing on a cursor. * **Errors arrive as human copy** — coded platform errors (quota, auth, transient) render family-appropriate wording with an action slot, never a raw code string. * **A composer that knows the turn state** — Enter sends, Shift+Enter newlines, IME composition is respected, Send becomes Stop mid-turn, and stopping keeps the partial reply marked “Stopped.” * **Accessibility as a default** — streaming text and status announce via live regions, every collapsible is keyboard-operable, prompts manage focus, animations respect reduced-motion. * **Scroll behavior that holds** — pinned to the latest message while streaming, released the moment the reader scrolls up, with a jump-to-latest affordance. A generated card that grows taller than the panel settles at its top, with the rest of the reply below it behind jump-to-latest, so the card is never scrolled out of view by its own growth. Long transcripts render windowed. Everything above is the `calm` preset — the end-user default. Unknown or future content types render as labeled, collapsed rows: **never blank, never raw JSON**. ## Give visitors a stable identity [Section titled “Give visitors a stable identity”](#give-visitors-a-stable-identity) The default setup carries identity via cookies, which is best-effort for cross-origin embeds. For durable anonymous continuity, mint a guest secret and hand it to the component — the same [identity model as the underlying SDK](/sdk/#give-visitors-a-stable-identity): ```tsx "use client"; import { GuueyChat } from "@guuey/chat/react"; import "@guuey/chat/styles.css"; /** 64 lowercase hex chars, minted once and persisted. Returns null if storage is blocked. */ function getGuestSecret(): string | null { try { const key = "guuey:guest-secret:your-app-id"; const existing = window.localStorage.getItem(key); if (existing && /^[0-9a-f]{64}$/.test(existing)) return existing; const bytes = crypto.getRandomValues(new Uint8Array(32)); const secret = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""); window.localStorage.setItem(key, secret); return secret; } catch { return null; } } export function AgentChat() { return ( ); } ``` `apiBaseUrl` is what turns on the batteries-included read paths: transcript history on reload, and resolution of generative-UI views by read (the component builds a reader over the same identity for you). Signed-in users work the same way as the SDK’s [bring-your-own-auth](/sdk/#signed-in-users-bring-your-own-auth): pass `getAccessToken` instead of `getGuestSecret`. If you construct your own `adapters` or `reader`, they always win over these defaults. Views resolve by read — bring an identity the read plane can see Generative-UI views mount by reading their `ui://` locator, and that read is authenticated. A **bearer** or a **guest secret** identifies the read on every environment and from any origin. Pure cookie identity (no `getGuestSecret`, no `getAccessToken`) also works — **but only same-host**: the guest cookie is host-only and `SameSite=Lax`, so it rides along when your page and the API share a host (a custom domain), and is never sent cross-site to the absolute `api..guuey.com` host. Cross-origin embeds — the widget iframe, native apps, a page on your own domain calling the absolute API host — need the guest secret; without it, cookie-only visitors there see views as “expired” (labeled, never blank). When both a cookie and a guest header are present on a same-host read, the cookie decides — the same precedence the chat stream uses. ## First customization [Section titled “First customization”](#first-customization) Three dials cover most products, all as props: ```tsx ``` * **`preset`** — `"calm"` (default, end-user) or `"debug"` (everything expanded, wire codes visible — the builder view). * **`strings`** — every piece of UI copy in one override map, which is also the i18n seam. `composerWaitingOnYou` (the composer’s line while a card waits on the visitor) is a required string: if you compose the lower-level components yourself, add it — or spread `defaultChatStrings` and override what you need. * **`policy`** — per-category behavior knobs (grouping thresholds, collapse defaults, which tool rows show, error wording, result size caps). When props stop being enough, the same package exports every layer underneath — replace one component, keep the rest; or take the headless view-model and render everything yourself. That ladder is the next page: [Customization & presets](/chat-customization/). ## Suggested prompts [Section titled “Suggested prompts”](#suggested-prompts) Chips (or any host-driven send) stay on the batteries-included path through the imperative handle — a `ref` (or the `onReady` callback, same object): ```tsx import { useRef } from "react"; import { GuueyChat, type GuueyChatHandle } from "@guuey/chat/react"; function Assistant() { const chat = useRef(null); return ( <>