Plugin manifest (manifest.json)

Each plugin must include a manifest.json at the root of its directory. The runtime reads this file to identify and validate the plugin before starting it.

All required fields

{
  "id": "hello-world",
  "name": "Hello World Plugin",
  "version": "0.1.0",
  "description": "A minimal plugin example",
  "author": "Your Name",
  "dotxVersion": ">=2.0.0",
  "permissions": [],
  "main": "main.js"
}

The runtime validates every field on load and will refuse to start a plugin if any required field is missing or invalid.

Fields

• id (string, required): Unique identifier for the plugin. Used to match plugin connections and store config.
• name (string, required): Human-friendly display name shown in the UI.
• version (string, required): Plugin version — must be valid semver (e.g. "1.0.0").
• description (string, required): Short description of what the plugin does.
• author (string, required): Author name or organization.
• dotxVersion (string, required): Dot X versions the plugin supports, as a semver range (e.g. ">=2.0.0"). Plugins exist from Dot X 2.0, and a 2.0.0 beta satisfies ">=2.0.0".
• permissions (string[], required): Permissions the plugin requests. Use [] if none are needed.
• main (string, required): Entry point file (e.g. "main.js").

Optional fields

• longDescription (string): Extended description shown in the marketplace.
• license (string): License identifier (e.g. "MIT").
• repository (object): { type: "git", url: "https://github.com/user/repo" }
• links (array): External links shown in the marketplace UI.

  [{ "title": "GitHub", "icon": "fa-brands fa-github", "url": "https://github.com/user/repo" }]

• packaging.include (string[]): Extra files or folders to bundle when building dist/<plugin-name>.dotxplugin.

  { "packaging": { "include": ["locales", "templates/email.html"] } }

• platforms (string[]): Restrict the plugin to specific operating systems — "windows", "macos", or "linux". Omit (or leave empty) to support all platforms.

Permissions

The permissions array is required. Use [] if the plugin needs no extra access. Add entries when your plugin needs:

• net (or network) — network access for MQTT, HTTP, WebSockets, etc.
• env — read the user's full environment. Without it, a plugin only sees the variables Dot X sets for it (DOTX_PLUGIN_*) and a few common ones such as PATH, NODE_ENV and TZ; anything else reads as undefined. Child processes inherit the same environment.
• run — spawn child processes
• ffi — native FFI bindings
• sys — system-level info
• read — unscoped filesystem read
• write — unscoped filesystem write
• hrtime — high-resolution timers
• all — all permissions (use sparingly)

Entries are case-insensitive; unknown values are ignored with a warning.

The runtime always grants scoped read/write to the plugin's own folder so it can store local config.

Validation

The runtime validates the manifest on startup and surfaces all errors at once:

• version must be valid semver
• dotxVersion must be a valid semver range compatible with the running Dot X version
• All required string fields must be non-empty
• permissions must be an array of strings
• platforms, when present, must be an array of "windows", "macos", or "linux"; the plugin is rejected if the current OS is not listed

The marketplace hides incompatible plugins by default; users can reveal them with a toggle.

Discovery

Dot X automatically discovers plugins by scanning for directories that contain a manifest.json. The id field uniquely identifies each plugin.