Hosting & runtime

You bring a declarative agent definition — a system prompt, a model, the MCP servers your agent uses, and an optional tool allowlist. Guuey runs it. There is no SDK to import, no polling loop to write, no event handler to register: configuration and a prompt are the whole integration.

Everything lives in one file, guuey.json, validated the same way by guuey dev, guuey deploy, and Guuey’s hosted platform — one contract everywhere.

This page is the how-to. For the machine underneath — the pod model, per-user pinning, pause and resume, and what happens at the edges — see How hosting works.

Note

Guuey is in public beta preview. If something on this page isn’t available on your account yet, it’s rolling out.

Isolated, long-running runtimes

Each agent runs in its own long-running pod, in its own namespace, on a default-deny network. Code-mode agents and MCP servers you host on Guuey are additionally sandboxed with gVisor — a much stronger isolation boundary than an ordinary shared container. A no-code agent runs Guuey’s own runtime image instead, and the worker that runs your turns is jailed inside the pod with a cleared, allowlisted environment. Long-running means your agent isn’t rebuilt on every request; it runs continuously from deploy to undeploy while the app has an active trial or plan (see Plans and the 7-day trial below). Nothing sleeps between conversations, so nothing has to wake up: the first message of the day is as fast as the last.

Hosted MCP servers work the other way by design — they scale to zero after about 30 minutes idle and wake on the next call.

The gVisor-isolated pod each hosted MCP server runs in matters most for compute workloads — code execution, binary tools like ffmpeg or pandoc, headless browser automation — the kind of thing most platforms can’t sandbox per tenant. The isolation model and data handling are covered in more depth on Security & isolation.

Plans and the 7-day trial

Billing is per app: every app you deploy carries its own plan, and every app starts on a 7-day trial from its first successful deploy — one always-on xs pod on the Free (trial) limits. When the trial ends and the app has no plan, Guuey pauses it: the pod scales to zero and a redeploy is refused until a plan is chosen, but nothing is deleted, and choosing a plan resumes the app automatically. One app per account (or workspace) runs without a plan at a time. The plan table, the full trial walkthrough — the trial slot, warning emails, what the paused surface shows, the API and CLI fields — and metered usage are on Plans & billing.

Personal and workspace apps bill separately. A workspace — a team, managed in the console under Settings → Workspace → your workspace — has its own wallet and its own trial slot, and owns its apps and hosted MCP servers; CI for a workspace-owned app authenticates with a workspace API key.

Pod sizes and scaling

Agent pods come in five sizes — xs, sm, md, lg, xl — picked at deploy time with guuey deploy --size (default xs). Which sizes an app may use, and how many pods it may run, come from its plan:

Plan	Sizes	Max pods per app
Free / trial	xs	1
Starter	xs–sm	2
Pro	xs–md	5
Scale	xs–xl	10

Pod count is a live knob: guuey agent config --max-pods <n> scales a running app with no redeploy (the platform converges within about five minutes), and the same flag rides guuey deploy --max-pods. Asking for more pods than the plan’s ceiling is refused with a 409 that names the ceiling; a higher per-app ceiling is a support request. Each user’s traffic stays pinned to one pod, so per-user session behavior is the same at any pod count.

The first always-on pod is included in the plan’s base fee; additional pods are metered by size and hours run — see Plans & billing. Runtime-image updates are automatic by default: --runtime-auto-update off (on guuey deploy or guuey agent config) pins the app to the image captured at its last deploy.

Streaming and history

Live responses stream over Server-Sent Events (SSE) directly from the pod running your agent — the client connects straight to the source, with no relay in between.

Every deployed agent has an always-on API address (<app-id>.agents.us-east-1.guuey.com in production) — printed by guuey deploy as Live at, and pollable at /readyz. The Domains page covers that hostname, the slug host that serves the agent’s page, and custom domains.

Conversation history is persisted automatically by the platform. Users can close the tab, come back later, and pick up the thread. You never build or operate a chat store.

Frameworks

Guuey is framework-adaptive: declare a framework in guuey.json, and the platform loads the matching runner, drives one turn per request, and streams the framework’s native events.

You declare	Runtime it drives
claude-agent-sdk	@anthropic-ai/claude-agent-sdk
openai-agents-sdk	@openai/agents
google-adk	@google/adk

For a no-code agent, that declaration plus your system prompt is everything — start from guuey config init or the console. If you’d rather write framework-native code, deploy a code-mode project — a worker bundle or Dockerfile the CLI builds and ships. Scaffold a working code-mode project from a template:

npx @guuey/create-agentic-app my-agent

MCP servers: bring your own

Agents declare their MCP servers in guuey.json in three flavors:

• hosted — Guuey builds and runs the server for you: a workspace-owned server deployed with guuey mcp deploy (scaffold one with guuey mcp new), or an existing one reused by id.
• colocated — the server runs alongside your agent inside its runtime, in a jail of its own spawned at pod boot, at no extra cost.
• external — any URL you point at.

An external server can carry its own credentials three ways: static headers (secrets referenced as ${env.NAME}), "federate": true (Guuey mints a per-user token the server verifies against Guuey’s issuer), or "credential": "oauth" — the server’s own OAuth authorization server signs each end user in, and Guuey brokers the tokens (see Connecting third-party accounts for what the user sees):

"mcpServers": {
  "linear": { "kind": "external", "url": "https://mcp.linear.app/mcp", "credential": "oauth" }
}

A colocated server is declared by source path: the deploy builds the directory and runs it as an HTTP child inside the agent pod — it rides the agent pod for free. devPort is where guuey dev serves it locally:

"mcpServers": {
  "notes": { "kind": "colocated", "source": "./mcps/notes", "devPort": 6782 }
}

The platform is MCP-server-agnostic: anything that speaks MCP works. The default server is mcp.ggui.ai — agents that keep it get generative UI out of the box, pushing real interactive interfaces to users instead of text-only replies. Generative UI, the protocol, and its SDKs are documented at docs.ggui.ai.

Tip

Stateless MCP servers that translate tool calls into HTTP requests against an existing API are the sweet spot for hosting on Guuey — they scale horizontally, wake on the next call after idling to zero, and cost nothing while nobody is calling them.

Local development

guuey dev --serve runs your agent locally under the same host harness used on Guuey pods, so your local loop matches production. When it works, ship it:

npm install -g @guuey/cli
guuey login
guuey deploy