Quickstart: build your first app

This is the full build loop, driven by a coding agent pointed at Robutler over MCP. Apps are built as widgets, so the build tools are named widget_*. By the end you will have a running app on a canvas, edited it live, and forked one.

The whole loop is: create to edit (reloading the live instance as you go) to mount and verify, then publish and snapshot where publishing is enabled, and remix to fork.

Connect Claude Code (or Codex, Cursor, or an AI assistant) to the Robutler MCP server. With Claude Code:

On first use it opens an OAuth flow in your browser. After you approve, the platform tools and the widget_* build tools are available. Full details, including other clients, are in Connect a coding agent over MCP.

From here on, you talk to your coding agent in natural language; it calls the MCP tools. The tool names below are what it invokes under the hood, shown so you know what is happening.

Ask your agent to create a new app:

It calls create_widget with { name: "hello-board" }. One call scaffolds the default collab-app template (Yjs sync, an agent command surface, host.kv prefs, a server function, tests, and an AGENT.md), lands it as a bundle folder you own, registers it as a private widget, and mints a dev token. Two ids come back, and they split all later work:

(widget_scaffold returns the same files without writing anything server-side, if you prefer to iterate locally first; templates: collab-app, minimal, webgpu, webrtc.)

Before writing anything non-trivial, have your agent read a shipped app — every first-party app is plain source at /widgets/<name>/ (collab-board is the clearest starting point) — and reuse its wiring. See App authoring.

Your agent calls widget_instantiate with { refId: <widgetContentId> } and gets { workspaceId, itemId, mountKind, canvasUrl }. Open the canvasUrl — the app is live.

Teach your agent the verification habit now, because a successful tool call is not a render:

This is where you spend most of your time. Edits land with widget_put_files and show up on reload — no publish step involved:

Then it reloads the running instance with the __reload builtin (workspace_widgets_invoke), screenshots it (__screenshot), and reads its console (workspace_widgets_logs). Two footguns worth knowing:

For deeper debugging, run the app locally against real platform data with the dev server: mint a token with widget_dev_token, then

When a server-side tool misbehaves, widget_fn_logs shows recent function invocations with status and errors.

Your app already runs privately; publishing puts it in the public catalog and gives it a life of its own:

Your agent calls widget_publish with { folderId }. In one transaction this mints (or reuses) a dedicated agent for the app, wires each declared tool as a custom function (plus an HTTP endpoint / agent-callable tool where exposed), stamps the app's command interface, and upserts the catalog and post rows. It returns { postId, agentId, widgetContentId, publicMcpAppUrl }, and republishing updates in place.

widget_publish and widget_snapshot appear in the toolset only when your account has publishing enabled — if they are absent, that is why; everything above still works and the app can be shared privately.

To cut an immutable, shareable version:

Your agent calls widget_snapshot with { workingWidgetId, listed: true, message: "first release" }. This freezes the bundle into a content-addressed version and, because listed: true, creates a marketplace post. An unchanged tree is a no-op. See Publishing and remix.

Listing your app is also how usage can earn you money. See Earn.

Anyone can fork an app they can use — published or shared with them — into a private, editable copy. No publish entitlement needed:

Your agent calls widget_remix with { refId } (the app's catalog refId or widget id). This clones the bundle into your account as a private widget and stamps the remix lineage, so the fork is attributed to its source. You get back { widgetContentId, folderId, canPublish }: mount the copy (step 2), edit it (step 3), and — where publishing is enabled — publish it as your own.