Publishing and remix

Three operations turn a bundle into a living, shareable, forkable app: publish, snapshot, and remix. Apps are built as widgets, so the tools are widget_publish, widget_snapshot, and widget_remix. This page covers what each does and how they relate. For arguments and return shapes, see MCP build tools.

widget_publish takes a bundle folder you own and deploys it as an app. It runs as a single transaction, so a mid-pipeline failure rolls back cleanly (no orphan agents, no half-wired functions). It is idempotent per (author, folder): republishing updates in place.

In one pass it:

It returns { postId, agentId, widgetContentId, publicMcpAppUrl }. The publicMcpAppUrl is the app's own outbound MCP App manifest at /api/widgets/<postId>/mcp: every published app is itself reachable as an MCP App. A republish replaces stale tool wiring rather than merging it, so a tool you remove actually disappears.

To put the published app on a canvas, call widget_instantiate with the widgetContentId and open the returned canvasUrl.

Publishing keeps a single working app you edit in place. widget_snapshot cuts an immutable, content-addressed version of that working app, so you have a frozen release that does not change when you keep editing.

Snapshotting freezes the bundle tree by cloning it. The clone shares each file's storage pointer with the live folder; a later edit to the live folder diverges (copy-on-write) and leaves the snapshot frozen. So a snapshot is cheap, and unchanged files dedup across versions. Each version records its Merkle treeHash and its parent version, forming an immutable version DAG.

Publishing a version is decoupled from listing it:

Snapshotting is idempotent: if the tree is byte-identical to the last version (same treeHash), it is a no-op that reuses the prior artifacts and just clears the dirty flag. On an update you can omit listed to reuse the prior choice (inferred from whether a post already exists), and pass a message for a commit-style version note.

It returns { versionId, widgetContentId, treeFolderId, treeHash, postId, deduped }.

widget_remix forks any published app (including your own) into your account. For a folder-bundle app it:

It returns { newPostId, newAgentId, newWidgetContentId, ordinal }. You then edit and publish the fork as your own.

A remix is attributed to its source. The fork's display name is composed as "<base> - Remix by @<username>", and the remix-of pointers thread the chain so a remix-of-a-remix re-attributes to the latest remixer rather than stacking suffixes. When you later snapshot the fork, the version records a best-effort fork link back to the source's published version, so the version graph spans forks too.

A fork inherits the source app's boot order, and for the realtime apps that order is load-bearing rather than incidental. The sequence that looks like ceremony — wait for a real room sync, only then bind the editor, stage any local store before merging it — is what stops a user editing a document that is open but not connected and losing the work on reload.

If your remix only changes UI, styling or commands, you inherit the correct behaviour and there is nothing to do. If you rewrite the boot or swap the editor, read host.collab first. Two edits in particular reintroduce silent data loss:

If you add an editing path the original did not have (a new panel, a new tool, a new command), route it through the same guard the app already uses: blockWrites / freezeYTypes from /widgets/shared/collab-readonly.js.

Neither shows up in casual testing: the app looks healthy, presence may even be live, and the loss only surfaces on someone else's reload.

Some kinds reject a remix:

These return a remix error rather than forking.

Listing a snapshot in the marketplace is how your app reaches people, and app usage is how you earn: makers earn through usage-based revenue sharing. See Earn.