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.mdto 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.
| Change | New version? |
|---|---|
| Fix a bug in your server | No — deploy your server |
| Change a tool's behaviour (same arguments) | No |
| Change a tool's input schema | No, but keep it backwards compatible (see below) |
Change a tool's description, add a tool | Yes |
Change the panel (ui/) or branding | Yes |
Add a grant, domain, account, scope or file param; change mcpUrl | Yes — human review and user consent |
| Add a folder or "Open with" handler, or widen one's access or file types | Yes — human review and user consent |
Add or change contributes.instructions, a prompt kit, a folder's label or reason, or an "Open with" label | Yes — human review |
| Use an app API 4 feature for the first time | Yes — 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:
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:
"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
needsHostApiand 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.