<!-- Source: https://docs.biosimulant.com/references/desktop-plugins/manifest -->

# 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

```json
{
  "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](/references/desktop-plugins/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)

**Warning:**

  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 |

```json
"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.

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

Every plugin should implement at least `plugin.health` and `plugin/shutdown`. See [Runtime & JSON-RPC](/references/desktop-plugins/runtime) 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.

```json
"entrypoint": "main.py"
```

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

```json
"entrypoint": "bin/my-plugin"
```

**Info:**

  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 |