Publishing
Changelog
Changes to the Chataway app platform, the manifest, the SDK and these docs.
#2026-10-24 — App API 4: AI, folders, agent runs, app chats
Chataway's app API is now at level 4. Versions that use anything below declare "requires": { "hostApi": 4 }; the store offers them only to Chataway versions that can run them. See App API levels.
AI
- Model calls from the panel:
app.models.run,app.models.stream(an async iterator of text deltas;cancel()orbreakstops it) andapp.models.usage, with atierhint (fast,balanced,best) instead of a model id. New grantmodels. See AI & prompt kits. - MCP sampling from your remote server, on the same grant:
ctx.sample()in the server helpers maps tiers tomodelPreferences. - A daily budget per app: 300 AI calls a day by default (Chataway's own apps: none), changed per app by the user on the app's page (0 = AI off). Every request counts, including sampling, agent-run turns and JSON retries. Over the limit →
budget. From app API 4 on, a local app'sctx.modelsneeds themodelsgrant too. - Prompt kits (
contributes.prompts): starters in the composer's Prompts menu and as chips in empty chats, with{{vars}}of kindtext,selectionorfile. They fill the composer, never send.app.prompts.list()andchat.compose({ promptId, values })from the panel. - Instructions (
contributes.instructions): one reviewed text in every chat of a project where the app is on, for every provider — now for cloud apps too.
Files
- Folders (
contributes.folders, grantfolders): the user grants a folder you declare; the panel works in it withapp.fs.list / read / write / rename / trash / restore / watch. Versions andifVersioncatch conflicting edits, backups make overwrites and trash undoable,fs-changeevents report changes by anyone. See Folders & Open with. - "Open with" (
contributes.fileHandlers): Open in … in the Files panel hands your panel one file (app.onOpen). - Storage zones (
storage):internal,readonlyanduserparts of your app's storage, for agents and other apps; sealed files for apps with server code. See Storage zones.
Agents and chats
- Agent runs (grant
agent):app.agent.run({ task, roots })from a click starts a tool loop with only file tools on the given roots (and your tools withappTools), no shell, no web; 30 tool calls by default (at most 60), 10 minutes, one at a time per project, shown in Activity with Stop. Local apps:ctx.agentRuns.start()inside an action the user clicked, one run per click. See Agent runs. - App chats (grant
chats):chat.create,chat.list,chat.open— real chats tagged with your app. See App chats. - Methods that speak or act for the user need a click in the panel, one call per click:
chat.send,chat.create,chat.open,folders.request,fs.trash,agent.run(needs-gesture). A message an app sends (chat.send,chat.createwithsend) is shown to the user first, until they allow that app to send (Chataway's own apps don't ask).
Store
- Catalog, app details and bundles answer per client level (
?hostApi=/X-Chataway-Host-Api):latestVersionandminimumVersionamong the versions the client runs,hostUpdatewhen a newer version needs a newer Chataway,needsHostApiwhen none runs. Newversions/latest/bundle. See Store API. - Review: instructions, prompt kits and folder and "Open with" wording are read in full whenever they change, plus folders, handlers, zones and the new grants. See the review guidelines.
Tools
@chataway/apps0.2: the bridge methods above (andchat.compose/chat.send, which the host already had), new error codesbudget,conflict,busy,needs-gesturewithdetails, a mock host with an echo model, an in-memory file system with versions and conflicts, and fake agent runs;ctx.sample()/sample()in the server helpers.
#2026-10-10 — Verified local apps, paid apps, automatic updates
Store
- Verified local apps: verified publishers can ship
servercode in a store bundle. Every version is reviewed with its full source; the install always runs isolated, macOS only. See Verified local apps. - Paid apps: monthly, yearly and one-time prices with an optional trial, Stripe payouts to your publisher account and a signed license on every call. See Selling your app.
- Chataway's own apps (e.g. Media) are now installed from the store, labelled By Chataway.
Updates
- Store apps update automatically unless the new version widens permissions (then the user approves it). Users can switch automatic updates off in Apps → Store.
- Required versions: mark a version required (with a message) and older copies pause until they update. See Versioning.
Kernel (local apps)
- Standing approvals: mark a cost-bearing card action
standing: trueand callctx.cards.allowStandingApprovals({ label }); users can then approve such actions ahead of time (per-project limit or "don't ask again for 1 hour" in a chat). - New services:
ctx.processes(with preview URLs a panel may frame),ctx.storage.folderUrl,ctx.panel.emit,ctx.models,ctx.toolchain,ctx.db; panel bridge:chat.compose,clipboard.readFiles,files.reveal,files.download. See Local apps.
#2026-10-01 — Build in Chataway, local apps, connectors
Apps are no longer only store apps. New pages: Build in Chataway, Local apps, Isolation & permissions, Connectors, Instructions for every agent and Sharing via GitHub.
Building
- App projects: Apps → + New app scaffolds a local or cloud app, links it in developer mode and starts a builder chat. The App strip shows status, version and reloads, with Inspector, Use in… and Share.
- Builder tools for the agent (every provider that has app tools):
app_status,app_reload,app_call_tool,app_inspect,app_validate,app_screenshot_panel. Load errors reach the agent's next turn by themselves. - Publish from Chataway: Share → Publish to store… uses the account the Mac is signed in with — publisher pick or create, store checks with Ask agent to fix, permission changes, version bump, build, pack, upload and review status. The CLI path is unchanged.
Local apps
server.tswith the kernel API (ctx.tools,cards,jobs,storage,settings,secrets,prompts,agentContext,actions,project,host.media,files,accounts).- Isolation: apps from GitHub run in their own process — always; your own with Run isolated. Files, child processes and signals limited; network only to
network.domainswith thenetworkgrant, through an egress proxy; the macOS sandbox on top. Everyctxcall returns a promise across the boundary —awaitthem. execis labelled full access to this Mac everywhere: programs inherit Chataway's macOS privacy permissions.
Sharing
- Install from GitHub:
owner/repo[@ref], GitHub URLs (incl. monorepo folders),npm:packages and MCP URLs. Pinned to one commit, labelled Unverified, optional agent check, updates with a diff and fresh consent for wider access, revocation by commit range, Open source to fork into an app project. - Push to GitHub from the App strip (private by default) and install links:
chataway.co/install?repo=…&ref=….
Connectors and dependencies
- Connectors: hosted MCP servers added by URL with MCP sign-in (protected resource metadata, dynamic client registration, PKCE +
resource); Popular connectors (Canva, Notion, Linear, Sentry, Stripe); approval before tools that aren't read-only. accounts[].auth: "mcp"for cloud apps whose MCP server does its own OAuth.- Dependencies:
requires.apps,requires.connectors,requires.optional. Apps wait for required apps; a newly required dependency is a widening (human review, consent again).
Instructions
ctx.prompts,ctx.agentContextand skills reach Codex (developer instructions), OpenCode (system), Cursor and Grok (a first-message preamble, re-sent on change) as well as Claude — one block per chat, capped at 6,000 characters.
Under the hood
- One install pipeline for every source (store, GitHub/npm, connector, folder, developer link): the same validation, install sheet, consent, update and uninstall steps, so every app page reads the same way.
- One manifest definition: the JSON Schema, the SDK's types, the validator copies, these docs' tables and the App builder skill's reference are all generated from it.
#2026-09-30 — Chataway apps v1
The first public version of the app platform.
Platform
- Cloud apps (Level 1): a manifest, a static panel and a remote MCP endpoint. The store accepts only cloud apps.
- Manifest v3 (
pluginApiVersion: 3):publisher,categories,branding,remote,accounts, toolfiles/confirm/account, and the cloud grantsfiles:receive,files:return,host:media,project:write. - Remote app runner: tools come from your MCP server over Streamable HTTP; only declared tools are registered; 120 s per call, 50 MB per response, 60 calls per minute per app.
- File hand-off with per-project consent,
prepare,acceptandmaxBytes; files returned from tools land in your app's storage. - Host services:
resize,crop,convert,compress,trim,frame,extract_audio,concat,probe. - Connected accounts: OAuth 2.1 authorization code + PKCE through
https://chataway.co/apps/oauth/callback. - Cards:
confirmapproval cards, elicitation as form cards,noticeandgalleryresult cards via_meta["chataway/card"]. - Panels: sandboxed webview with a CSP from
remote.domains, host-drawn views and badges, live theme tokens.
Store
- Publishers with DNS domain verification, developer tokens and device sign-in.
- Automated checks on every upload; human review for first versions, permission changes, unverified publishers and flagged checks; automatic approval otherwise.
- Ed25519-signed versions and revocation list.
Tools
@chataway/apps0.1: manifest types and validator, panel bridge with a mock host,theme.css, server helpers, and thechatawayCLI (init,dev,validate,pack,login,logout,publish,status).create-chataway-app0.1.- JSON Schema at
/schemas/app-manifest-v3.json.