Chataway Developers
Publishing

Updating & versioning

How versions work, which changes users have to consent to again, how updates reach users, and how to withdraw a bad version.

#Versions

version in plugin.json is semver: MAJOR.MINOR.PATCH, with an optional pre-release (1.3.0-beta.1).

  • Every upload needs a new, greater version than any version of the app you've uploaded before — including rejected ones.
  • Versions are immutable once uploaded. To change anything, bump the version.
  • Use CHANGELOG.md to tell users what changed; it's shown with the update.

Your server is not versioned by the store — you deploy it whenever you like. That's the point of cloud apps: most fixes need no new version at all. You only publish a new version when the manifest or panel changes.

ChangeNew version?
Fix a bug in your serverNo — deploy your server
Change a tool's behaviour (same arguments)No
Change a tool's input schemaNo, but keep it backwards compatible (see below)
Change a tool's description, add a toolYes
Change the panel (ui/) or brandingYes
Add a grant, domain, account, scope or file param; change mcpUrlYes — human review and user consent
Add a folder or "Open with" handler, or widen one's access or file typesYes — human review and user consent
Add or change contributes.instructions, a prompt kit, a folder's label or reason, or an "Open with" labelYes — human review
Use an app API 4 feature for the first timeYes — with requires.hostApi: 4

#Keep your server compatible

Users update at their own pace, so your server is called by several app versions at once. Keep it working for every version that's still published:

  • Add optional arguments, don't rename or remove required ones.
  • Keep old tools until no published version declares them, then retire them.
  • If you must break something, add a new tool id, ship a version that uses it, and remove the old tool later.

The app version isn't sent with calls, so design for overlap rather than branching on version.

#How updates reach users

Chataway checks the store for newer signed versions in the background (about a minute after it starts, then every few hours) and, by default, installs them by itself when they ask for nothing new. Users can turn this off with Update apps automatically in Apps → Store; they then see an update badge and a notification per new version instead.

When an update widens permissions — a new grant, domain, account, scope or file param, a new or wider folder or "Open with" handler, or a different mcpUrl — the app stays on its current permissions in each project until the user reviews the change. Until then, the app shows Needs consent and its new version's tools aren't active in that project. The user sees exactly what's new:

Acme Assets 1.3 wants more accessAcme Assets
New: reach cdn.example.com · receive audio files you choose to upload.
AllowNot now

So: widen rarely, and explain every addition in permissions. Narrowing (removing a grant or domain) never needs consent.

#Required versions

For a security fix, mark a published version required on your app's page in the Developer area (Mark as required, with an optional message), or with POST /api/developer/apps/:appId/versions/:version/required and { "required": true, "message": "…" }. The store then reports it as the app's minimumVersion. Any copy older than that is paused — no tools, your message and an Update now button in its panel — until it updates; with automatic updates on, that happens at once (unless the required version widens permissions, in which case it waits for the user's OK). Unmark it the same way with "required": false.

To pull a version from everyone instead, use revocation.

#App API levels

Each Chataway release implements an app API level. Today's level is 4. A version says the lowest level it needs in requires.hostApi; without it, the version is level 3 and runs on every Chataway the store supports.

Level 4 adds instructions, prompt kits, model calls, folders and "Open with", agent runs, app chats and storage zones. If a version uses any of them — contributes.instructions, prompts, folders, fileHandlers, storage, or the models, folders, agent or chats grants — it must say so:

json
"requires": { "hostApi": 4 }

Without it, chataway validate fails with hostapi.required.

#What older Chataway versions see

Chataway sends its level with every store request (?hostApi= and X-Chataway-Host-Api). The store answers each Mac with the versions it can run:

  • The newest version it can run is the one it installs and updates to. If you publish 2.0.0 with "hostApi": 4, a Chataway at level 3 stays on your newest level-3 version.
  • A newer version it can't run shows as "Update Chataway to get Acme Notes 2.0.0" (the listing's hostUpdate). The installed version keeps running; it isn't paused.
  • An app with no version it can run is listed with needsHostApi and can't be installed there. Chataway versions too old to send a level don't see it at all.
  • A download by exact version is still served; Chataway's installer refuses a version above its level with "Needs a newer Chataway". A copy that is already installed above the level (say, after Chataway was downgraded) is paused with the same message.

Older versions keep calling your server, so keep their tools working (see Keep your server compatible).

#Moving an existing app to app API 4

Publish your first API-4 version as a required version. Required versions are counted only among the versions a Mac can run, so:

  • every Chataway at level 4 with an older copy updates to it (and pauses until it does);
  • every older Chataway keeps your last level-3 version, running normally, with the "Update Chataway" notice.

If the API-4 version also asks for new access (a new grant or folder), the update waits for each user's OK, as any widening update does.

#Pre-release testing

Test a new version in developer mode before you publish it: chataway dev runs your folder as a separate DEV app next to the store version. Point --mcp-url at a staging server to test server and app changes together.

#Yanking

If you published a version that shouldn't be used — it uploads to the wrong place, or leaks data — ask for it to be yanked from the developer dashboard, then publish a fixed version.

A yanked version is added to the signed revocation list. Every Mac checks the list hourly and at startup and disables the version: its tools are removed from chats and its panel closes, with a note to the user. When a fixed version is available, it's offered as an update.

The review team can also yank a version, with a reason sent to you — see the review guidelines.

#Revocation vs. disconnect

Yanking is about code you shipped. If instead you need to cut off a user's access — a leaked token, an abusive account — do it on your side: revoke the OAuth tokens on your server. Chataway will see 401s and ask the user to reconnect.