Appearance
Security And Current Limits
An installed Mantis extension runs your code inside the Mantis page. This page explains what it can reach, what constrains it, and what is not supported yet.
Trust model
Only install extensions from sources you trust.
An extension can:
- run JavaScript inside its extension host
- run JavaScript inside its panel
- access Mantis data covered by granted permissions
- set the point selection if granted
selection:write - create bags if granted
bags:write - open and close panels if granted
panels:write - register and execute commands if granted
commands:execute - store extension state through
workspaceStateandglobalState - invoke its Python backend if granted
backend:invoke - run Python dependencies declared in
requirements - access the network from its backend if
networkistrue
The install dialog shows the declared permissions, contributed panels, backend status, and backend network request.
Packages published on a map
A map can offer extensions to its readers. An offer is not an install: nothing runs until a reader chooses Install and confirms the consent step, and the listing a reader sees carries no asset and no backend source, so no package code is in the reader's hands before agreement.
Installing an offer is the same decision as installing a package from a file:
- the package is validated by the same rules described on Packaging and installation: the same manifest shape, permission list, path rules, size caps and text-only encoding.
- the consent step shows the same fields - publisher, version, declared permissions, panels, backend actions, and the backend network request.
- the restrictions on this page apply unchanged, including the panel sandbox, the RPC and backend timeouts, and backend network defaulting to off.
Two properties belong to an offer specifically:
- the agreement names the package it agreed to, not the coordinate. The consent step carries the digest of the package the listing described, and a package replaced at that coordinate after the listing was read is refused rather than run. A refusal of that kind states that the map's offer changed; read the current listing and decide again.
- the map can withdraw an offer. Withdrawal stops offering the package, and it also stops the extension for a reader who accepted it: a reader's install of a published package names the map's copy rather than holding one of its own, so the code goes when the map's copy goes. The reader's decision is kept - the coordinate, whether it is enabled, and the version it was made about - and it takes effect again if the map publishes that same package at the coordinate.
An offer adds a second publisher to the trust question - the account that attached the package to the map - on top of whoever wrote the code. The manifest's own publisher string is what an offer and the consent step state; the account Mantis observed publishing is recorded on the publication and on the reader's own install of it, and is not displayed beside that string yet. Neither is a review of the package.
A publication does not give the account that published it any reach into a reader's account: it cannot enable, disable or remove an extension for a reader, and it cannot install anything on a reader's behalf.
Browser access
Host and panel code must use mantis / window.mantis to communicate with Mantis. Permissions are checked on SDK calls. If permission is missing, the call fails.
The extension host runs in a Web Worker. Panels run in sandboxed iframes with sandbox="allow-scripts" only (no allow-same-origin). That keeps the panel on an opaque origin so it cannot read the parent’s cookies, localStorage, or DOM. Do not add allow-same-origin for extension panels without a full security review.
For durable UI state, panels should use window.mantis.workspaceState / window.mantis.globalState (see SDK reference). That storage is handled in the parent page over the RPC bridge, like the host worker's context.workspaceState / globalState.
They are separate browser execution contexts, but they are still trusted extension code.
Hard limits
These are the edges an author actually hits. None of them are configurable from a package.
| Limit | Value | What happens when you exceed it |
|---|---|---|
| RPC timeout, panel and host | 30 s | The promise rejects with Mantis extension RPC timeout: <method>. |
| Command invocation timeout | 30 s | The promise rejects with a command timeout. |
| Python backend execution | 30 s by default | The invocation fails. Combined with the RPC cap, a synchronous long analysis is not possible. |
| Package size | 25 MB | Import is refused. |
| Single file size | 5 MB | Import is refused. |
| File encoding | UTF-8 text only | Import is refused with "Extension file must be UTF-8 text". No images, fonts, or wasm can be shipped in a package; inline them as data URIs or fetch them at runtime. |
| Versions of one id | Newest only | Older versions stay on the server but the workspace loads only the highest version of each extension id. |
Extension state (workspaceState and globalState) is localStorage in the Mantis page, not account state. It is per-browser-profile, is not synced across devices, and is lost when site data is cleared.
Backend execution
Python backends run with additional safeguards. Mantis:
- validates backend paths
- installs requirements into a per-extension cache
- applies execution timeouts
- defaults backend network mode to no network
These safeguards reduce accidental damage, but they do not make unknown code safe. Treat backend code as trusted.
Permissions are not a marketplace review
Permissions limit access at runtime, but they do not prove an extension is safe. A malicious extension with maps:read can still read map data visible through that permission.
Before installing, check:
- who published it, and for an offer, which account attached it to the map
- why it needs each permission
- whether backend network is requested
- whether requirements are expected
- whether the package source is trusted, including the map the offer arrives with
Verified publishers
The marketplace marks the publishers the deployment vouches for. A listing carries verified_publisher, and a mark is drawn beside the publisher on the marketplace card, on the version row of one extension, and on the step that takes the agreement.
The mark is the deployment saying it knows whose account published the package. It is not a review of the package, not a signature over it, and not a permission: a verified publisher can still ship code that does worse than it claims, and the review fields beside it are what state what a review found.
The record is about the account rather than about a version, and a deployment records it for its own catalogue with manage.py verify_catalog_publisher --publisher <account id> [--unverify] on the API. Recording an account reaches every listing that account has published, including versions published before the recording, and withdrawing it stops reaching all of them at once; nothing about the standing is stored in a listing. A listing read from a deployment that does not record the flag is shown as unverified rather than as missing the field.
Current limits
The current extension system is beta. It now has background activation, durable commands, deactivate hooks, manifest.main, activationEvents, selection.set in both runtimes, basic extension state, and the verified-publisher mark on a listing.
Not supported yet:
- calling native Mantis commands. The native command allowlist is empty (see below).
- menus contribution point
- settings contribution point
- binary assets in a package
- marketplace signing
- the recorded publishing account shown on an offer, which a publication stores and a reader's install names but no reader-facing step displays
- extension dependency graph
- stable SDK compatibility field like
engines.mantis - secret storage
- extension update channels
- CSP-per-extension origin isolation
Command lifetime limit
Commands can be registered from the extension host:
js
exports.activate = async function activate(context) {
const disposable = await mantis.commands.registerCommand(
'demo.sample-panel.refresh',
refresh,
);
context.subscriptions.push(disposable);
};Host-registered commands survive panel close and are cleaned up when the host deactivates.
Panels may still register commands:
js
const disposable = await window.mantis.commands.registerCommand(
'demo.sample-panel.refresh',
refresh,
);Panel-registered command handlers live with that panel instance. If the panel closes, those handlers are disposed.
Native command execution
window.mantis.commands.execute can execute commands that an extension registered. Native Mantis commands go through an allowlist, and that allowlist is currently empty, so the effective answer today is that no built-in Mantis action is reachable from an extension. Anything not registered by an extension throws.
commands:execute therefore grants far less than its name suggests. It does not let an extension drive the Mantis UI.
Data handling guidance
Extension authors should:
- request the smallest permission set possible
- avoid sending sensitive data to external services
- keep backend network disabled unless required
- validate payloads before processing
- show clear errors instead of silently swallowing failures
- document what the extension reads and writes
Future direction
The contribution points reserved in the manifest (menus, settings) suggest where the platform is headed, and a native command allowlist exists in code waiting to be populated. Nothing on that list has a ship date, so build against what is documented above rather than what is reserved.