# What the marketplace.json File Defines in OpenAI Plugins

> Discover what the marketplace.json file defines in OpenAI Plugins. Learn about plugin catalogs, source paths, installation policies, and authentication rules today.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-06-24

---

**The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file acts as the central manifest for the OpenAI Plugins repository, defining the complete catalog of discoverable plugins along with their source paths, installation policies, and authentication rules.**

The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file serves as the single source of truth for plugin discovery in the OpenAI Plugins ecosystem. Located by default at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), this JSON manifest enumerates all officially supported plugins that Codex and other OpenAI agents can load. Understanding its structure is essential for developers who want to register new plugins or build custom agents that consume the plugin catalog.

## Structure of the marketplace.json File

The manifest consists of three primary sections that define the marketplace metadata and plugin inventory.

### name and interface Fields

The `name` field specifies the logical identifier for the marketplace itself (e.g., `"openai-curated"`). The `interface` object contains UI-level metadata, including the `displayName` that surfaces in marketplace interfaces.

### The plugins Array

Each entry in the `plugins` array is a plugin descriptor containing:

- **`name`** – The unique plugin identifier
- **`source`** – Location data with `source: "local"` and a relative `path` pointing to the plugin directory
- **`policy`** – Rules governing `installation` (e.g., `"AVAILABLE"`) and `authentication` (e.g., `"ON_INSTALL"`)
- **`category`** – High-level grouping for UI filtering (e.g., `"Productivity"`)

## How Plugin Discovery Uses marketplace.json

The plugin-discovery system leverages this manifest to perform three critical functions:

1. **Enumerate supported plugins** – Generates the complete list of agents available to OpenAI products like Codex
2. **Resolve source directories** – Maps plugin names to their physical locations so the runtime can load each plugin's [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and associated assets
3. **Apply security policies** – Enforces `installation` and `authentication` rules that dictate when plugins are shown, how users grant permissions, and which products can access them (e.g., `products: ["CODEX"]`)

## Working with marketplace.json

### Adding a New Plugin Entry

To register a new plugin, append an object to the `plugins` array in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json):

```json
{
  "name": "my-awesome-plugin",
  "source": {
    "source": "local",
    "path": "./plugins/my-awesome-plugin"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

```

The new plugin becomes immediately discoverable by any agent that reads the manifest.

### Loading the Manifest in Node.js

Agents consume [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) to discover available plugins programmatically. The following pattern mirrors how Codex internally handles plugin discovery:

```javascript
import fs from 'fs';
import path from 'path';

const marketplacePath = path.join(
  process.env.HOME,
  '.agents',
  'plugins',
  'marketplace.json'
);
const marketplace = JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));

for (const plugin of marketplace.plugins) {
  console.log(`Found plugin ${plugin.name} in ${plugin.source.path}`);
}

```

This snippet reads the manifest from the default location and iterates over every plugin entry.

### Checking Installation Policies

You can query the manifest to determine if a plugin is available for installation:

```javascript
function canInstall(pluginName) {
  const p = marketplace.plugins.find(p => p.name === pluginName);
  return p?.policy?.installation === 'AVAILABLE';
}

```

This function checks the `policy.installation` field to verify availability before attempting installation.

## Related Files and Automation

Several utilities in the repository interact with [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json):

- **[`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py)** – Scaffolds new plugins and optionally updates [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) with new entries
- **[`.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)** – Documents marketplace file locations for personal versus repository-wide configurations
- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** (lines 10-12) – Documents the default location and relationship to [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/api_marketplace.json)

## Summary

- **The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file** is the canonical manifest located at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) that defines all discoverable plugins in the OpenAI Plugins repository.
- **It contains three main sections**: `name` (marketplace identifier), `interface` (UI metadata), and `plugins` (array of plugin descriptors).
- **Each plugin descriptor** specifies the `source` path for loading, `policy` rules for installation and authentication, and `category` for organization.
- **The discovery system** uses this file to enumerate plugins, resolve their directories, and enforce access policies for OpenAI agents including Codex.

## Frequently Asked Questions

### Where is the marketplace.json file located in the OpenAI Plugins repository?

By default, [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) resides in the `.agents/plugins/` directory at the repository root. According to the repository's [`README.md`](https://github.com/openai/plugins/blob/main/README.md), this location serves as the standard path for the central plugin catalog, though agents can also check user-specific directories like `~/.agents/plugins/` for personal marketplace configurations.

### What fields are required when defining a plugin in marketplace.json?

Each plugin entry must include a `name` (unique identifier), a `source` object containing `source: "local"` and a relative `path` to the plugin directory, and a `policy` object defining `installation` status (typically `"AVAILABLE"`) and `authentication` requirements (such as `"ON_INSTALL"`). The `category` field provides optional but recommended UI grouping.

### How does Codex use the marketplace.json file for plugin discovery?

Codex and other OpenAI agents read [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) to enumerate available plugins, resolve each plugin's source directory to load its [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, and apply installation policies that control which plugins appear in the UI and what permissions they require. This process is documented in the plugin-eval README (lines 143-148).

### Can I manually edit marketplace.json to add custom plugins?

Yes, you can manually append plugin descriptors to the `plugins` array in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), or use the provided Python utility at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) which automates the scaffolding and registration process. When editing manually, ensure the `source.path` points to a valid directory containing a proper [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file.