Packaging And Installation

Mantis accepts extension packages as:

• .mantisx
• .zip
• .json

For real extensions, prefer .mantisx or .zip. A JSON package is useful for small examples and debugging.

Zip package layout

The package must contain mantis.extension.json either at the root:

my-extension.zip
  mantis.extension.json
  dist/extension.js
  dist/panel.js
  dist/styles.css
  backend/main.py

Or inside one single top-level folder:

my-extension.zip
  my-extension/
    mantis.extension.json
    dist/extension.js
    dist/panel.js
    dist/styles.css
    backend/main.py

Packages with multiple unrelated top-level folders are rejected.

JSON package layout

A JSON package contains the manifest, browser assets, and backend files inline:

{
  "manifest": {
    "manifestVersion": 1,
    "id": "demo.inline-extension",
    "name": "Inline Extension",
    "version": "0.1.0",
    "main": "dist/extension.js",
    "activationEvents": ["onPanel:main"],
    "contributes": {
      "panels": [
        {
          "id": "main",
          "title": "Inline Panel",
          "entry": "dist/panel.js"
        }
      ]
    }
  },
  "assets": {
    "dist/extension.js": "exports.activate = function () {};",
    "dist/panel.js": "document.getElementById('root').textContent = 'Hello';"
  },
  "backend": {}
}

This is convenient for fixtures, but larger extensions should use zip-based packages.

File groups

Mantis splits files into two groups:

Group	Source	Exposed to panel?
assets	Any file not under backend/	Yes
backend	Files under backend/	No

Extension host main, panel entry, scripts, and styles must refer to files in assets.

Backend entry must refer to a file in backend.

Validation rules

The backend validates packages before installation and again during installation.

Validation checks include:

• package size
• UTF-8 text files
• manifest shape
• supported permissions
• supported contribution points
• safe relative paths
• extension host main existence
• panel asset existence
• backend entry existence
• user/project access

Absolute paths and paths containing .. are rejected.

Install flow

When a user imports an extension:

1. Mantis validates the package.
2. Mantis shows a trust dialog with the extension name, version, panels, permissions, backend status, and network request.
3. If the user confirms, Mantis installs the package for that user and project.

Packages are validated before installation. If any referenced asset, backend file, permission, or manifest field is invalid, installation fails.

Where extensions appear

Installed extension panels appear in:

Verticals > Extensions

Extensions can be disabled, enabled, or removed from the installed extensions list in the same menu.

Enable, disable, and uninstall

Disabling an extension hides its contributed panels, closes open extension tabs, and stops its extension host. Uninstalling removes the installed package for the current user and project.

Backend dependency caches may remain until the server cleans them or the package/version changes.

Size and encoding limits

Limit	Value
Package size	25 MB
Any single file	5 MB

Packages are UTF-8 text only

Every file in a package is decoded as UTF-8 during import. Anything that is not valid UTF-8 text fails with “Extension file must be UTF-8 text”, which means you cannot ship images, fonts, wasm, or any other binary asset. Inline small assets as data URIs in your JavaScript or CSS, or fetch them at runtime from a URL.

Beyond the hard caps, keep packages small:

• bundle only what the panel needs
• avoid large datasets inside the extension package
• fetch project data through the SDK instead of shipping static copies
• keep Python dependencies minimal

Versioning

The server stores extensions by id and version, so multiple versions coexist on disk. Use normal version increments when publishing updates:

{
  "id": "demo.sample-panel",
  "version": "0.1.1"
}

Version strings may contain only letters, numbers, ., _ and -, because the value becomes a directory name. A semver build suffix such as 1.0.0+build.3 is rejected.

Only the newest version runs

However many versions of an id are installed, the workspace loads exactly one: the highest version. Older builds stay on the server but are never activated, so installing an older package to test a regression will not have the effect you expect unless you remove the newer one first.

Changing the id creates a separate extension from Mantis’s perspective.

Recommended build output

If you use a bundler, produce plain browser JavaScript and CSS:

dist/
  extension.js
  panel.js
  styles.css

Do not rely on imports from the parent Mantis app. Bundle host dependencies into extension.js and panel dependencies into your panel output.