Chataway Developers
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() or break stops it) and app.models.usage, with a tier hint (fast, balanced, best) instead of a model id. New grant models. See AI & prompt kits.
  • MCP sampling from your remote server, on the same grant: ctx.sample() in the server helpers maps tiers to modelPreferences.
  • 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's ctx.models needs the models grant too.
  • Prompt kits (contributes.prompts): starters in the composer's Prompts menu and as chips in empty chats, with {{vars}} of kind text, selection or file. They fill the composer, never send. app.prompts.list() and chat.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, grant folders): the user grants a folder you declare; the panel works in it with app.fs.list / read / write / rename / trash / restore / watch. Versions and ifVersion catch conflicting edits, backups make overwrites and trash undoable, fs-change events 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, readonly and user parts 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 with appTools), 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.create with send) 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): latestVersion and minimumVersion among the versions the client runs, hostUpdate when a newer version needs a newer Chataway, needsHostApi when none runs. New versions/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/apps 0.2: the bridge methods above (and chat.compose / chat.send, which the host already had), new error codes budget, conflict, busy, needs-gesture with details, 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 server code 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: true and call ctx.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.ts with 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.domains with the network grant, through an egress proxy; the macOS sandbox on top. Every ctx call returns a promise across the boundary — await them.
  • exec is 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.agentContext and 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, tool files / confirm / account, and the cloud grants files: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, accept and maxBytes; 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: confirm approval cards, elicitation as form cards, notice and gallery result 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/apps 0.1: manifest types and validator, panel bridge with a mock host, theme.css, server helpers, and the chataway CLI (init, dev, validate, pack, login, logout, publish, status).
  • create-chataway-app 0.1.
  • JSON Schema at /schemas/app-manifest-v3.json.