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.

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.