Know HTML? You can write plugins.
A plugin is essentially a web page (HTML / CSS / JS). Write the page, then package it with the plugin packager inside CosmosBox into a .cbplugin file — send it to anyone and it installs and runs.
A faster path: one-click AI generation — describe what you want in the AI chat ("make a digital wooden fish"), and the AI produces an installable plugin.
A plugin can be a single file or a multi-file directory (.cbplugin is essentially a zip package):
my-plugin/
├── manifest.json // plugin manifest (required)
├── index.html // entry page (entry points to it)
├── style.css // optional assets
└── app.js // optional scripts{
"pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d", // UUID v4 unique ID (auto-generated by the packager)
"id": "mobi.reader", // legacy short ID (compat)
"name": "MOBI Reader",
"version": "1.2.0",
"author": "YuzhouHe",
"description": "Reads MOBI / AZW3 ebooks",
"icon": "📖", // Emoji / image URL / Base64
"entry": "index.html",
"permissions": ["file.read", "storage"],
"fileTypes": ["mobi", "azw3"] // file routing: external files open automatically by type
}| Field | Required | Description |
|---|---|---|
pluginId | ✓ | UUID v4 unique ID, system-level collision protection; let the packager auto-generate it |
id | — | Legacy short ID (e.g. mobi.reader); omit for new plugins, kept for compatibility |
name | ✓ | Display name of the plugin |
version | ✓ | Semantic version, e.g. 1.2.0 |
author | — | Author name |
description | — | One-line description, shown in the plugin market |
icon | — | Emoji, image URL or Base64 image |
entry | ✓ | Relative path of the entry file (usually index.html) |
permissions | ✓ | Permission declarations (e.g. file.read / storage), granted one by one in the permission center |
fileTypes | — | Declared file extensions for file routing (auto-open from outside) |
.cbplugin; paid/private plugins → .encplugin (AES encryption + double password confirmation to prevent typos)pack_plugins.ps1 script — run it once after editing plugins to regenerate all .cbplugin files (auto-skips .git / node_modules / build directories)..cbplugin | .encplugin | |
|---|---|---|
| Purpose | Public sharing | Paid / private distribution |
| Content | Plaintext zip | AES encrypted |
| Import | Install directly | Enter password (auto password dialog when opened externally) |
⚠️ Encrypted plugin passwords cannot be recovered — losing the password means the plugin can never be decrypted. Keep it safe.
Plugins run inside a sandboxed WebView — open and secure at once:
| Mechanism | Description |
|---|---|
| CSP header injection | Meta tag + HTTP header dual path, restricts external script loading |
| eval / Function disabled | Full Object.defineProperty coverage, no dynamic code execution |
| Network rate limit | Plugin network requests limited to 60/min to prevent abuse |
| Path isolation | Plugins can only read/write their own sandbox directory (path traversal protection) |
| Permission center | permissions declarations + per-item grants, every action auditable |
| JS bridge | Native capabilities via bridge API (storage / clipboard / files…), base library auto-injected by the host |
Plugin IDs use UUID v4 (122 bits of random entropy) — collisions are practically impossible, so duplicate user-side IDs never overwrite or delete each other. We recommend letting the packager generate it; when specifying manually, use the full UUID format (8-4-4-4-12) — the packager validates it.
Describe what you need directly in the CosmosBox AI chat:
You → Make a digital wooden fish; tapping it makes a sound with animation
AI → ✅ Plugin "Digital Wooden Fish" generated — install & run with one clickAI-generated plugins get the base library injected automatically (storage / clipboard / dark-mode adaptation) and can be installed from the plugin center right away; not happy with it? Ask the AI to keep editing it in the editor page.