How to Configure marketplace.json for OpenAI Plugins: A Complete Guide

To configure marketplace.json, create a JSON manifest at .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 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 in two locations depending on your use case:

• Repository-wide: .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/<plugin-name> resolve relative to your home directory (~/plugins/<plugin-name>) rather than the repository root.

Core Structure and Schema

The marketplace.json file follows a strict schema defined in .agents/skills/plugin-creator/references/plugin-json-spec.md. Here is the complete structure:

{
  "name": "<catalog-identifier>",
  "interface": {
    "displayName": "<human-readable marketplace title>"
  },
  "plugins": [
    {
      "name": "<plugin-folder-name>",
      "source": {
        "source": "local",
        "path": "./plugins/<plugin-folder-name>"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "<UI bucket>"
    }
  ]
}

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.
• 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:

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

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

{
  "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, 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/<plugin-name> regardless of whether the marketplace file is repo-wide or personal; resolution happens relative to the file's location.

Summary

• Place marketplace.json at .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 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 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 to ~/.agents/plugins/marketplace.json in your home directory. Update the path values in each plugin's source object to point to ~/plugins/<plugin-name> instead of the repository location. The personal configuration takes precedence and allows customization without modifying shared repository files.

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