Plugin Manifest

Every plugin requires a plugin.json file at the root of its package. This file declares the plugin’s identity, capabilities, permissions, and UI contributions.

Full Schema

{
  "id": "your-org.your-plugin",
  "name": "My Plugin",
  "description": "A brief description of what your plugin does.",
  "version": "0.1.0",
  "kind": "tool_provider",
  "entrypoint": "main.py",
  "platforms": ["darwin", "linux", "windows"],
  "architectures": ["aarch64", "x86_64"],
  "permissions": [
    { "key": "workspace.read", "title": "Read workspace files" },
    { "key": "events.emit", "title": "Emit plugin events" }
  ],
  "capabilities": [
    "plugin.health",
    "my.custom.method"
  ],
  "ui_contributions": [
    { "slot": "sidebar.item", "icon": "wrench", "label": "My Plugin" },
    { "slot": "page.main", "component": "my-page" }
  ],
  "auth_modes": [],
  "min_desktop_version": "0.1.0",
  "update_channel": "stable"
}

Required Fields

Field	Type	Description
`id`	`string`	Unique plugin identifier in reverse-domain format (e.g., `your-org.plugin-name`). This is the permanent identity of your plugin across all versions.
`name`	`string`	Human-readable display name shown in the UI.
`version`	`string`	Semantic version (e.g., `1.0.0`). Each registry upload must use a unique version.
`kind`	`string`	Plugin type: `"agent_provider"` or `"tool_provider"`. Determines how the desktop app renders your plugin’s UI.
`entrypoint`	`string`	Path to the executable or script that the host will spawn. Relative to the plugin install directory.

Optional Fields

Field	Type	Default	Description
`description`	`string`	`null`	Description shown in the marketplace and plugin detail views.
`platforms`	`string[]`	All	Target operating systems: `"darwin"`, `"linux"`, `"windows"`.
`architectures`	`string[]`	All	Target CPU architectures: `"aarch64"`, `"x86_64"`.
`permissions`	`object[]`	`[]`	Permissions your plugin needs. Each has a `key` and optional `title`.
`capabilities`	`string[]`	`[]`	JSON-RPC methods your plugin implements.
`ui_contributions`	`object[]`	`[]`	UI slots your plugin contributes to. See UI Contributions.
`auth_modes`	`string[]`	`[]`	Authentication methods your plugin supports (e.g., `"chatgpt"`, `"api_key"`).
`min_desktop_version`	`string`	`null`	Minimum desktop app version required.
`update_channel`	`string`	`"stable"`	Release channel: `"stable"` or `"beta"`.

Plugin ID Convention

Use reverse-domain notation for your plugin ID:

your-org.plugin-name

Examples:

openai.codex (an OpenAI agent plugin)
biosimulant.reference-echo (a Biosimulant reference plugin)
acme-labs.data-exporter (a third-party tool plugin)

⚠️

The plugin ID is permanent. Changing it creates a new plugin, and existing installations won’t receive updates.

Permissions

Permissions declare what your plugin needs access to. Users can configure approval policies (allow, deny, or prompt) per permission.

Permission Key	Description
`workspace.read`	Read workspace files and lab configurations
`workspace.mutate`	Modify workspace files, models, and lab configurations
`command.execution`	Execute CLI commands on the user’s machine
`events.emit`	Emit events that the desktop app can listen to

"permissions": [
  { "key": "workspace.read", "title": "Read workspace" },
  { "key": "workspace.mutate", "title": "Modify workspace" }
]

The title field is optional and provides a human-readable label shown in the approval UI.

Capabilities

Capabilities list the JSON-RPC methods your plugin implements. This helps the host and other plugins understand what your plugin can do.

"capabilities": [
  "plugin.health",
  "echo.repeat",
  "data.export"
]

Every plugin should implement at least plugin.health and plugin/shutdown. See Runtime & JSON-RPC for the full protocol.

Entrypoint

The entrypoint is the command the host spawns when your plugin is activated. It receives JSON-RPC messages on stdin and writes responses to stdout.

"entrypoint": "main.py"

For compiled binaries, place them in the bin/ directory:

"entrypoint": "bin/my-plugin"

Files under bin/ and runtime/ directories are automatically marked as executable when packaged into a .bsiplugin archive.

The host sets these environment variables before spawning your entrypoint:

Variable	Description
`BIOSIMULANT_PLUGIN_INSTALL_DIR`	Absolute path to the plugin’s installation directory
`BIOSIMULANT_PLUGIN_DATA_DIR`	Absolute path to a private writable directory for plugin state
`BIOSIMULANT_DESKTOP_VERSION`	Version of the desktop app running the plugin

Overview Runtime & JSON-RPC