What is a .aip?

A ChatOSS app is a folder of plain HTML, CSS, and JavaScript with an app.json manifest, zipped, with the zip named <anything>.aip. No frameworks, no build step, no npm, no server. The user installs it by dropping the file onto ChatOSS's Apps app; it appears in their dock with its icon and runs in a sandboxed window.

Like .ipa and .apk files are zips, a .aip is just a zip — the way to distribute an app for ChatOSS.

How apps get installed

Three paths, one pipeline — the folder is always zipped → validated → installed:

• Drop a .aip on the Apps app — the classic path. Zip your files, rename the zip to yourapp.aip, drop it on the Apps app.
• The Create app — scaffold the manifest through a form, edit files, preview live, then publish straight into the dock or export the .aip.
• An AI agent in the Code app — Code has a publish_app tool that installs a finished app folder directly into the user's dock: the user gets a Publish / Cancel prompt, and on Publish the folder is zipped, validated, and installed (same pipeline as dropping a .aip on the Apps app).

The validator rejects a manifest that isn't valid JSON, an id that isn't lowercase reverse-DNS (or is com.chatoss.*), a missing entry file, a missing icon, or an app over 20 MB unpacked — with readable errors for each.

Folder structure

my-app/
├── app.json      ← manifest (REQUIRED, at the root)
├── index.html    ← entry point (REQUIRED; the name is configurable via "entry")
├── main.js       ← any JS/CSS/images, any names, any subfolders
├── style.css
├── icon.svg      ← the dock icon (recommended)
└── libs/         ← vendored third-party browser libraries, if needed

Files are served at real URLs at runtime, so relative references all work: <script src="main.js">, <link rel="stylesheet" href="style.css">, <img src="icon.svg">, and fetch('data.json') (for reading the app's own bundled files).

Constraints:

• app.json and the entry HTML must be at the zip root (zipping the parent folder is also accepted — one shared root directory is stripped).
• Unpacked size limit: 20 MB.
• Need a JS library? Vendor its prebuilt browser file into libs/ and load it with a script tag. There is no npm install.

Read the manifest for every app.json field, and the runtime bridge for what your code can do once it runs.

Publishing to users

Install a .aip with the same id and it updates in place. If the new version requests permissions the installed one didn't have — a new capability, data key, or global tool — ChatOSS diffs the manifests and shows the exact additions for the user's approval; denying keeps the installed version as-is. Write complete manifests from v1 so a later update never has to ask for more.

Updates

Bump version in app.json whenever you ship a change. For apps installed from a GitHub repo, the OS periodically compares the published version (the repo's app.json or its latest GitHub release) against the installed one, and when the published version is strictly newer the user sees an Update button that downloads and updates the app in place. A downgrade is never offered. After a major update, commit and push the bumped app.json so your users get that Update button.