What Is the Codex Plugin Manifest? File Structure, Schema, and Validation

A Codex plugin manifest is a JSON configuration file located at .codex-plugin/plugin.json that defines the plugin's identity, capabilities, authentication requirements, and permissions for the OpenAI Codex runtime.

The Codex plugin manifest serves as the single source of truth for how the OpenAI platform discovers, validates, and loads third-party extensions. Every plugin bundled in the openai/plugins repository must include this structured JSON file to register its skills with the Codex assistant and render properly in the plugin marketplace.

Manifest File Location and Naming Convention

The Codex runtime enforces a strict directory structure for plugin discovery. Each plugin must store its manifest at the path .codex-plugin/plugin.json relative to the plugin's root directory.

Real-world examples in the repository include:

• plugins/zoom/.codex-plugin/plugin.json — Configuration for the Zoom integration
• plugins/vercel/.codex-plugin/plugin.json — Configuration for the Vercel deployment plugin

When a new plugin is added to the repository, committing a correctly formatted .codex-plugin/plugin.json alongside the plugin's code is mandatory for automatic registration.

Core Manifest Fields and Schema

The manifest uses a standardized JSON schema to declare the plugin's metadata and functional capabilities. The manifestVersion field specifies which version of the manifest format the plugin uses, ensuring backward compatibility as the platform evolves.

Required Metadata Fields

• name — Human-readable plugin name (e.g., "Zoom") displayed in the marketplace
• description — Short summary explaining the plugin's purpose
• version — Semantic version string following major.minor.patch format
• author — Individual creator or organization responsible for the plugin

Functional Configuration Fields

• capabilities — Array of skill names the plugin exposes to the Codex assistant
• auth — Authentication requirements specification (OAuth flows, API keys, etc.)
• schema — JSON schema describing the inputs and outputs for each declared skill
• icons — URLs or relative paths to plugin icon assets for UI generation
• permissions — Required access scopes (e.g., read:calendar, write:files)

How the Codex Runtime Uses the Manifest

The Codex platform processes the manifest file to perform four critical operations:

1. Validation — Verifies plugin structure against the official schema before loading
2. Skill Exposure — Makes declared capabilities available to the Codex assistant for invocation
3. Security Enforcement — Applies authentication and permission checks when the plugin is called
4. UI Generation — Renders marketplace elements including icons, descriptions, and version information

According to the openai/plugins source code, the runtime specifically references plugins/codex-security/schemas/scan-manifest.schema.json to validate manifests during the loading process.

Reading and Validating Manifest Files

Developers can programmatically interact with Codex plugin manifests using standard file system operations and JSON schema validators.

Loading a Manifest in Node.js

import { readFile } from 'fs/promises';
import path from 'path';

async function loadManifest(pluginDir) {
  const manifestPath = path.join(pluginDir, '.codex-plugin', 'plugin.json');
  const raw = await readFile(manifestPath, 'utf-8');
  return JSON.parse(raw);
}

// Usage
loadManifest('plugins/zoom')
  .then(manifest => console.log('Zoom plugin version:', manifest.version))
  .catch(err => console.error('Failed to read manifest:', err));

Validating Against the Official Schema

The repository includes a JSON Schema at plugins/codex-security/schemas/scan-manifest.schema.json for automated validation. Use the ajv-cli tool to verify your manifest before submission:

# Install the JSON schema validator

npm i -g ajv-cli

# Validate a plugin's manifest

ajv validate -s plugins/codex-security/schemas/scan-manifest.schema.json \
            -d plugins/codex-security/examples/completed-scan/scan-manifest.json

Documentation in plugins/plugin-eval/README.md confirms that the manifest must reside at .codex-plugin/plugin.json for the evaluation tools to process the plugin correctly.

Summary

• The Codex plugin manifest is a JSON file located at .codex-plugin/plugin.json in every plugin directory
• Required fields include name, description, version, author, capabilities, auth, schema, icons, permissions, and manifestVersion
• The Codex runtime uses the manifest to validate structure, expose skills, enforce security, and generate marketplace UI
• Developers should validate manifests against plugins/codex-security/schemas/scan-manifest.schema.json before committing to the repository

Frequently Asked Questions

Where is the Codex plugin manifest file located?

The manifest file must be placed at .codex-plugin/plugin.json relative to the plugin's root directory. For example, the Vercel plugin stores its manifest at plugins/vercel/.codex-plugin/plugin.json within the repository structure.

What fields are required in a Codex plugin manifest?

At minimum, the manifest must include name, description, version, author, capabilities, auth, schema, icons, permissions, and manifestVersion. These fields define the plugin's identity, security requirements, and functional capabilities for the Codex runtime.

How do I validate my Codex plugin manifest?

Use the JSON Schema validator ajv-cli against the official schema located at plugins/codex-security/schemas/scan-manifest.schema.json. Run: ajv validate -s [schema-path] -d [manifest-path] to check your file before submission.

What happens if the manifest file is missing or malformed?

The Codex runtime will fail to load the plugin during the validation phase. The platform requires a correctly formatted manifest at .codex-plugin/plugin.json to register the plugin, expose its skills to the assistant, and enforce authentication checks.

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