> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Package structure and manifests

> A Mini App is a regular MiniMax Plugin with a miniapp.json declaration and two runtime payloads, one for the page and one for Node.

## Directory layout

```text theme={null}
sales-board/
├── .minimax-plugin/
│   └── plugin.json          # plugin manifest
├── package.json             # only the mcode extension is needed
├── icon.png
├── servers.mcp.json         # optional
├── skills/                  # optional
└── miniapp/
    ├── miniapp.json         # MiniApp declaration
    ├── client/              # page payload
    │   ├── index.html
    │   └── client-api.ts    # optional: type checking only
    └── node/                # Node payload
        ├── server.mjs
        └── miniapp-api.ts   # optional: type checking only
```

New packages created by `init` use this layout. The host still reads the earlier `liveboard/` format, and updating an old package doesn't require converting it.

## Plugin manifest: plugin.json

`.minimax-plugin/plugin.json` is the single source of truth for plugin identity, metadata, icon, Skills, MCP, and Apps. Mini App authoring never reinterprets or clears these fields.

```json .minimax-plugin/plugin.json theme={null}
{
  "schemaVersion": 1,
  "name": "sales-board",
  "displayName": "Sales Board",
  "version": "1.0.0",
  "description": "Shows the verified sales pipeline.",
  "author": "Your Name",
  "icon": "icon.png",
  "category": "Business",
  "exampleQueries": ["Open my sales pipeline dashboard."],
  "apps": [],
  "mcpServers": [],
  "skills": []
}
```

* `name` is a lowercase machine name of up to 80 characters that starts with a letter and may use digits and `.` `_` `-` as separators. It is the Mini App's `pluginId`.
* `version` uses SemVer. `description`, `author`, and every `exampleQueries` entry must be non-empty.
* `icon` points to a PNG, JPEG, or WebP inside the package. `init` provides a default icon.
* `apps`, `mcpServers`, and `skills` keep their ordinary plugin meaning; use empty arrays for capabilities you don't have.

## Entry declaration: package.json

```json package.json theme={null}
{
  "mcode": {
    "schemaVersion": 2,
    "miniApp": "./miniapp/miniapp.json"
  }
}
```

The root `package.json` only needs this extension. The host never reads or runs engineering metadata such as `packageManager`, lockfiles, build scripts, or dependencies.

## Mini App declaration: miniapp.json

```json miniapp/miniapp.json theme={null}
{
  "schemaVersion": 1,
  "artifacts": {
    "client": ["./miniapp/client"],
    "node": ["./miniapp/node"]
  },
  "runtime": {
    "kind": "process",
    "entry": "./miniapp/node/server.mjs",
    "lifecycle": "on-demand"
  },
  "surface": {
    "path": "/dashboard",
    "window": { "width": 960, "height": 700, "resizable": true }
  },
  "mcpEndpoints": [],
  "hostConnectorAccess": { "providers": ["notion"] },
  "agentAccess": ["session.run"],
  "agentConcurrency": 4
}
```

See [miniapp.json fields](https://agent.minimax.io/docs/miniapp/reference/manifest.md) for every field. Key points:

* `artifacts.client` and `artifacts.node` are both required. They define what the host hashes, adopts, and publishes; they can be source directories rather than build output, and they may overlap.
* `runtime.entry` is the Node entry, ending in `.js`, `.mjs`, or `.cjs`, inside the Node payload. `lifecycle` is always `on-demand`: enabling or scanning a plugin never starts the service.
* `surface.path` is the page route served by the Node service.
* `hostConnectorAccess` and `agentAccess` are explicit grants; leave them out and you don't get them. Declare them only when the runtime really needs them.

The example requests only Connector access and Agent execution. Reading user sessions separately requires `agentAccess: ["session.read"]`, calling host tools requires `toolAccess: ["call"]`, and using the microphone requires `deviceAccess: ["microphone"]`. Combine declarations as needed; users can switch each one off in plugin details.

Camera and system notifications are available since v3.1.9, declared with `deviceAccess: ["camera"]` and `deviceAccess: ["notifications"]`, respectively. When using either capability, set `engines.mcode` to `>=3.1.9` or a higher minimum version. See [Device permissions](https://agent.minimax.io/docs/miniapp/reference/manifest.md#devices) for details.

When using newer interfaces, declare a minimum host version in this `miniapp/miniapp.json`, such as `"engines": { "mcode": ">=3.1.5" }`. See [Versions and capability detection](https://agent.minimax.io/docs/miniapp/reference/manifest.md#compat) for the limits of version gating and `capabilities.has(name)`.

## Payload rules

* The host doesn't install dependencies or run builds. Ship something ready to run, and bundle or vendor third-party runtime dependencies into a payload directory. Prefer Node built-ins and browser APIs.
* `node_modules` is build state: it is never published and must not sit inside a declared payload.
* Use portable relative paths: no absolute paths, `..`, backslashes, or symlinks, and nothing outside the package.
* Every file in a payload except `node_modules` goes into the digest. Delete logs, caches, temporary files, and anything else you don't want published before you publish.