# How to Configure marketplace.json for OpenAI Plugins: A Complete Guide > Learn how to configure marketplace.json for OpenAI Plugins. This guide covers defining marketplace metadata, plugin entries, installation policies, and UI categories for your plugins. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-28 --- **To configure [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json), create a JSON manifest at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) (repo-wide) or `~/.agents/plugins/marketplace.json` (personal) that defines your marketplace metadata, plugin entries, installation policies, and UI categories.** The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file serves as the central manifest that tells Codex (OpenAI ChatGPT) which plugins belong to your marketplace and how they should be presented to users. Whether you are curating plugins for a team repository or building a personal collection, understanding how to properly configure this file is essential for controlling plugin discovery and installation behavior. ## File Location and Scope You can place [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) in two locations depending on your use case: - **Repository-wide**: [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) — Shared across your team and version-controlled with the repository. - **Personal**: `~/.agents/plugins/marketplace.json` — User-specific configuration that overrides or supplements the repo-wide settings. Both locations use identical schema structures. When using the personal location, path values like `./plugins/` resolve relative to your home directory (`~/plugins/`) rather than the repository root. ## Core Structure and Schema The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file follows a strict schema defined in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md). Here is the complete structure: ```json { "name": "", "interface": { "displayName": "" }, "plugins": [ { "name": "", "source": { "source": "local", "path": "./plugins/" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "" } ] } ``` ### Top-Level Metadata The root object requires two critical fields: - **`name`**: A unique identifier for the marketplace (e.g., `openai-curated`, `my-team-plugins`). - **`interface.displayName`**: The human-readable title shown in the Codex UI. **Note**: This belongs under `interface`, not at the root level or inside individual plugin objects. ### Plugin Entry Configuration Each object in the `plugins` array represents a single plugin and requires: - **`name`**: Must match both the plugin folder name and the `name` field inside that folder's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). - **`source`**: Currently always `"local"` for this repository, with a `path` relative to the marketplace file location. - **`category`**: UI grouping label such as `Productivity`, `Developer Tools`, or `Data Analysis`. ### Policy and Authentication Settings The `policy` object controls availability and security: - **`installation`**: Determines initial visibility. - `AVAILABLE` — User can install manually (default). - `INSTALLED_BY_DEFAULT` — Pre-installed for all users. - `NOT_AVAILABLE` — Hidden from the marketplace. - **`authentication`**: Specifies when credentials are requested. - `ON_INSTALL` — Prompt during installation (default). - `ON_USE` — Prompt when the plugin is first invoked. - **`products`** (optional): Array restricting the entry to specific OpenAI products (e.g., `["CODEX"]`). ## Practical Configuration Examples ### Adding a New Plugin Entry To register a new plugin called `example-plugin`, append this object to the `plugins` array in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json): ```json { "name": "example-plugin", "source": { "source": "local", "path": "./plugins/example-plugin" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ``` Ensure the folder `plugins/example-plugin/` exists and contains a valid [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file. ### Modifying Installation Policies To make the Linear plugin install by default for all team members, update the `policy.installation` value while preserving other fields: ```json { "name": "linear", "source": { "source": "local", "path": "./plugins/linear" }, "policy": { "installation": "INSTALLED_BY_DEFAULT", "authentication": "ON_INSTALL" }, "category": "Productivity" } ``` Changes take effect immediately when Codex reloads the marketplace configuration. ### Creating a Personal Marketplace For individual customization without modifying the repository, create `~/.agents/plugins/marketplace.json`: ```json { "name": "personal-curated", "interface": { "displayName": "My Personal Tools" }, "plugins": [ { "name": "custom-util", "source": { "source": "local", "path": "./plugins/custom-util" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" }, "category": "Developer Tools" } ] } ``` Place your plugin files in `~/plugins/custom-util/` to match the relative path structure. ## Validation Rules and Constraints When you configure [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json), adhere to these rules derived from the OpenAI Plugins specification: - Every plugin entry **must** include `policy.installation`, `policy.authentication`, and `category`. - New entries are **appended** to the `plugins` array unless you explicitly reorder existing entries. - The `displayName` field must reside under `interface`, not inside individual plugin objects. - Path values remain `./plugins/` regardless of whether the marketplace file is repo-wide or personal; resolution happens relative to the file's location. ## Summary - Place [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) for team-wide configuration or `~/.agents/plugins/marketplace.json` for personal use. - Define top-level `name` and `interface.displayName` to identify your marketplace in the Codex UI. - Configure each plugin with `source` (local paths), `policy` (installation and authentication behavior), and `category` (UI grouping). - Use `installation: "INSTALLED_BY_DEFAULT"` to pre-install plugins for users, or `authentication: "ON_USE"` to defer credential prompts. - Reference the specification at [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) for advanced validation rules. ## Frequently Asked Questions ### Where should I place marketplace.json for team-wide use? Place the file at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) in your repository root. This location is version-controlled and shared across all team members who clone the repository. The live marketplace file used by the OpenAI Plugins repository follows this convention. ### What values are valid for the installation policy? The `policy.installation` field accepts three string values: `NOT_AVAILABLE` (hidden from users), `AVAILABLE` (visible and manually installable), and `INSTALLED_BY_DEFAULT` (automatically enabled for all users). If omitted, the system defaults to `AVAILABLE`. ### Can I restrict plugins to specific OpenAI products? Yes. Add a `products` array inside the `policy` object to limit visibility to specific platforms. For example, `"products": ["CODEX"]` restricts the plugin to Codex-only environments, preventing it from appearing in other OpenAI product interfaces. ### How do I migrate from a repo-wide to a personal marketplace? Copy the contents of [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) to `~/.agents/plugins/marketplace.json` in your home directory. Update the `path` values in each plugin's `source` object to point to `~/plugins/` instead of the repository location. The personal configuration takes precedence and allows customization without modifying shared repository files.