The manifest

The manifest is the single contract between a module and the Hanabi platform. Schema version 5.0. The canonical validator is module_manifest.py; the CLI and SDK mirror it so you get the same verdict locally and on upload.

Full example #

{
  "schema_version": "5.0",
  "id": "example-module",
  "name": "Example Module",
  "version": "0.1.0",
  "summary": "Describe what this module does.",
  "entrypoints": {
    "ui": "ui/index.html",
    "worker": "worker/main.py"
  },
  "permissions": ["files.read", "files.write", "jobs.create", "jobs.emit_progress"],
  "filesystem": {
    "root": "Modules/Example Module",
    "folders": [
      { "id": "imports",   "name": "Imports",   "role": "input",     "path": "Modules/Example Module/Imports",   "create_on_install": true, "allowed_extensions": ["xlsx", "csv"], "description": "Source inputs." },
      { "id": "exports",   "name": "Exports",   "role": "output",    "path": "Modules/Example Module/Exports",   "create_on_install": true, "description": "Finished outputs." },
      { "id": "workspace", "name": "Workspace", "role": "workspace", "path": "Modules/Example Module/Workspace", "create_on_install": true, "description": "Scratch space." }
    ]
  },
  "dependencies": {
    "runtimes": [
      { "name": "browser", "version": "modern", "required": true },
      { "name": "python",  "version": ">=3.11",  "required": false }
    ],
    "python": ["pillow>=10.0"],
    "node": [],
    "office": { "word": false, "excel": false, "powerpoint": false },
    "services": []
  },
  "ui": {
    "window": {
      "default_width": 960, "default_height": 620,
      "min_width": 680,     "min_height": 460,
      "resizable": true,    "allow_multiple": false
    },
    "popouts": []
  },
  "desktop": {
    "file_associations": ["md", "txt"],
    "jump_list": [{ "id": "new-note", "label": "New note" }]
  },
  "portal": { "tags": ["documents"], "icon_data_url": null, "banner_url": null, "screenshot_urls": [] }
}

Field reference #

Identity

entrypoints

permissions

A list drawn only from this allowlist (anything else fails validation):

Permissions sit in four tiers (full table in capability-api.md):

• baseline — implied by install (files.read/write/manage, jobs.create/queue, settings.self, notifications, storage.read, data.store, modules.use).
• consent-gated — the *.all file perms and the client.* flags: declaring isn't enough, the user must consent (a prompt at install or first use); they never reach other modules' folders.
• admin-approved — granted by publishing review (network.fetch, worker.execute, jobs.schedule, client.wasm).
• admin-HIGH — default-deny; an admin must grant each one per module and set its quota at review (worker.native, worker.service, network.fetch.broad, the big worker.execute tiers). See examples/modules/media-toolkit-worker.

Permissions are declared here, granted at install, and enforced at runtime by the capability bridge — see capability-api.md.

filesystem

The module's entire view of the VFS. It can never see anything outside this tree.

Folder role conventions: input = imports the module reads; output = generated files (the runtime writes finished outputs here); workspace = scratch state; cache = disposable; config = reusable settings/templates.

dependencies

How a module declares its requirements. Surfaced at validation and review.

ui.window

desktop (optional — desktop integration)

Opt into shell integration. Both keys are optional; invalid entries are dropped during normalization.

"desktop": {
  "file_associations": ["md", "txt"],
  "jump_list": [
    { "id": "new-note", "label": "New note" },
    { "id": "search",   "label": "Search notes" }
  ]
}

portal (metadata, not validated as contract)

Free-form listing metadata: tags, icon_data_url, banner_url, screenshot_urls. Used by the Module Store / Developer Portal for presentation. The first tag becomes the catalog category for published modules.

Validation behavior #

• validate_module_manifest() returns { status: "valid" | "needs_review", issues: [...] }.
• The manifest is normalized first (missing fields filled with safe defaults), then validated, so a partial manifest still produces useful issues rather than crashing.
• Path safety (.., leading /, backslashes) is checked for every entrypoint and filesystem path.

Planned additions (backward-compatible) #

See `architecture.md` §3.1. Designed but not yet live: runtime.kind, entrypoints.worker_handler, capabilities.requests (folder-scoped grants), platform.min_version / platform.api.