# How to Add a Plugin to the marketplace.json File in OpenAI Plugins > Learn to add a plugin to the marketplace.json file by creating a JSON entry with key details. Follow our guide to easily integrate your plugin into the OpenAI plugins repository. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-23 --- **To add a plugin to the marketplace.json file, create a JSON entry containing the name, source, policy, and category fields, then append it to the plugins array in either the personal manifest at `~/.agents/plugins/marketplace.json` or the repository-wide manifest at `/.agents/plugins/marketplace.json`.** The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file serves as the central manifest that tells Codex which plugins are available and how they should be presented to users. When working with the **openai/plugins** repository, properly registering your plugin in this file makes it discoverable in the Codex plugin marketplace. This guide walks you through the exact steps, required fields, and validation rules based on the official plugin specification. ## Locate the Correct marketplace.json File ### Personal Marketplace Personal plugins reside in `~/.agents/plugins/marketplace.json`. Use this location for plugins specific to your individual Codex environment that should not be shared with other repository contributors. ### Repository-Wide Marketplace For plugins shared across a team or repository, edit `/.agents/plugins/marketplace.json`. According to the specification 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) (lines 98-104), this is the standard path for repo-wide plugin discovery that Codex reads when loading the workspace. ## Structure the Plugin Entry ### Required Fields Each entry must include four mandatory fields: **name**, **source**, **policy**, and **category**. The specification 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) (lines 130-158) defines these fields as follows: - **name**: Must match the folder name under `plugins/` and the `name` field in the plugin's own [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest. - **source**: An object specifying the source location. For local plugins, use `{"source": "local", "path": "./plugins/"}`. - **policy**: Contains at least `installation` (default value: `AVAILABLE`) and `authentication` (default value: `ON_INSTALL`). - **category**: A free-form string used for grouping plugins in the Codex UI. ### Example Entry Append a new object like this to the `plugins` array: ```json { "name": "my-awesome-plugin", "source": { "source": "local", "path": "./plugins/my-awesome-plugin" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ``` ## Insert the Entry into the Array Append the new object to the `plugins` array in the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file. Preserve the JSON structure and ensure valid syntax, including proper commas between array elements. If an entry for the same plugin already exists, replace it only when you intend to overwrite the previous configuration. The full file structure follows this pattern: ```json { "name": "openai-curated", "interface": { "displayName": "Codex official" }, "plugins": [ { "name": "existing-plugin", "source": { "source": "local", "path": "./plugins/existing-plugin" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Utilities" }, { "name": "my-awesome-plugin", "source": { "source": "local", "path": "./plugins/my-awesome-plugin" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ] } ``` ## Validate Against the Plugin Manifest Ensure the `name` field in your [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) entry matches the name defined in the plugin's internal manifest file at `//.codex-plugin/plugin.json`. For example, the Zoom plugin references its configuration at [`/plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main//plugins/zoom/.codex-plugin/plugin.json), and the marketplace entry must align with that internal name to ensure Codex can locate the source files correctly. ## Commit Your Changes After editing the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file, commit the changes to version control to make them permanent and versioned. Run the standard Git workflow: ```bash git add .agents/plugins/marketplace.json git commit -m "Add my-awesome-plugin to marketplace" git push ``` ## Summary - The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file controls plugin visibility in Codex and lives at either `~/.agents/plugins/marketplace.json` (personal) or `/.agents/plugins/marketplace.json` (repo-wide). - Each entry requires **name**, **source**, **policy**, and **category** fields as 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). - The `name` must align with the folder name under `plugins/` and the internal [`/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main//.codex-plugin/plugin.json) manifest. - Local plugins use a source object with `"source": "local"` and a relative path pointing to the plugin directory. - Commit changes to version control to update the marketplace for all users. ## Frequently Asked Questions ### What is the difference between personal and repo-wide marketplace.json files? Personal plugins live in `~/.agents/plugins/marketplace.json` and are only available to your individual Codex instance. Repo-wide plugins live in `/.agents/plugins/marketplace.json` and are shared with anyone using that repository. According to the specification 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), Codex checks both locations to build the complete plugin list, with personal entries taking precedence in case of conflicts. ### What happens if the name field does not match the plugin folder? The plugin will fail to load or appear incorrectly in the marketplace. The `name` field in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) must exactly match the folder name under `plugins/` and the name specified in the plugin's own [`/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main//.codex-plugin/plugin.json) file. This alignment ensures Codex can resolve the `source.path` and locate the plugin's entry point correctly. ### Can I use installation policies other than AVAILABLE? Yes, the `installation` field within the `policy` object supports different values to control availability. While `AVAILABLE` is the default, you can specify other policies defined in the specification to restrict installation behavior. The `authentication` field similarly defaults to `ON_INSTALL` but can be configured based on your security requirements to prompt for credentials at different lifecycle stages. ### How do I verify my marketplace.json changes are valid? Check that your JSON syntax is valid and that all required fields (name, source, policy, category) are present. Verify that the `source.path` points to an existing directory containing a valid [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file. After committing, Codex will reload the marketplace automatically and surface any configuration errors in the system logs.