How to Add a Plugin to the marketplace.json File in OpenAI Plugins

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 <repo-root>/.agents/plugins/marketplace.json.

The 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 <repo-root>/.agents/plugins/marketplace.json. According to the specification in /.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 (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 manifest.
• source: An object specifying the source location. For local plugins, use {"source": "local", "path": "./plugins/<plugin-name>"}.
• 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:

{
  "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 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:

{
  "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 entry matches the name defined in the plugin's internal manifest file at /<plugin-name>/.codex-plugin/plugin.json. For example, the Zoom plugin references its configuration at /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 file, commit the changes to version control to make them permanent and versioned. Run the standard Git workflow:

git add .agents/plugins/marketplace.json
git commit -m "Add my-awesome-plugin to marketplace"
git push

Summary

• The marketplace.json file controls plugin visibility in Codex and lives at either ~/.agents/plugins/marketplace.json (personal) or <repo-root>/.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.
• The name must align with the folder name under plugins/ and the internal /.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 <repo-root>/.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, 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 must exactly match the folder name under plugins/ and the name specified in the plugin's own /.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 file. After committing, Codex will reload the marketplace automatically and surface any configuration errors in the system logs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}