How to Deploy an OpenAI Plugin: Complete Guide to Publishing in the Marketplace

Deploying an OpenAI plugin requires packaging a valid manifest file (plugin.json), hosting the endpoints on a serverless platform like Vercel or AWS Lambda, and submitting the manifest URL through the OpenAI developer console for marketplace validation.

OpenAI plugins are distributed as code bundles that expose capabilities through a structured manifest and HTTP endpoints. According to the openai/plugins repository, transforming a local development project into a live marketplace service involves three logical phases: packaging the plugin artifacts, choosing a serverless deployment target, and publishing to the OpenAI Plugin Marketplace.

Phase 1: Package the Plugin

Every OpenAI plugin begins as a repository containing a valid manifest and runtime code. The root of the repository must include a README.md describing the plugin, while the core configuration lives in .codex-plugin/plugin.json.

The manifest file defines the plugin's identity, authentication model, and API specifications. As implemented in the openai/plugins repository, this file must reside at plugins/<plugin-name>/.codex-plugin/plugin.json and include required fields such as schema_version, name_for_human, and the api section pointing to your OpenAPI specification.

Phase 2: Choose a Deployment Target

The marketplace requires your plugin to expose HTTP endpoints that handle requests from ChatGPT. Most plugins in the mono-repo target serverless platforms including Vercel, AWS Lambda, Azure Functions, or Docker containers.

The chosen platform must satisfy two requirements: it must host the endpoints referenced in your manifest's api section, and it must provide environment variables (e.g., OPENAI_API_KEY, ZOOM_APP_BASE_URL) without exposing them in source control. The repository includes a generic Vercel deployment skill that wraps vercel CLI commands, documented in plugins/vercel/skills/deployments-cicd/SKILL.md.

Phase 3: Publish to the OpenAI Plugin Marketplace

Once your endpoint is live, submit the manifest URL (e.g., https://my-plugin.example.com/.codex-plugin/plugin.json) via the OpenAI developer console. The marketplace performs automated validation: it checks TLS configuration, verifies the manifest syntax, and confirms that required endpoints respond correctly.

Specifically, the marketplace queries two mandatory routes: /health for availability checks and /api/info for metadata. Failure to implement these routes results in rejection during the integration test phase.

Step-by-Step Vercel Deployment Walkthrough

The openai/plugins repository uses Vercel as its reference implementation. The following workflow demonstrates the complete deployment process:

1. Create the Manifest

Place your plugin.json in plugins/<my-plugin>/.codex-plugin/. This file tells the marketplace what the plugin does, its auth model, and the URLs of its skills. Reference the Zoom plugin's manifest at plugins/zoom/.codex-plugin/plugin.json for a production example.

2. Configure Vercel

Add a vercel.json at your repository root to define serverless functions and build settings. This configuration maps HTTP routes to your handler functions, typically located in an api/ directory.

3. Deploy to Production

Run the following commands to create a preview deployment and promote it to production:

# Install Vercel CLI (once)

npm i -g vercel

# Login (interactive)

vercel login

# Deploy preview (creates https://my-plugin-<hash>.vercel.app)

vercel --confirm

# Promote to production

vercel --prod

These commands correspond to the abstractions defined in plugins/vercel/skills/deployments-cicd/SKILL.md, which maps vercel deploy to preview creation and vercel promote to production releases.

4. Verify Endpoints

Validate your deployment using the Vercel CLI to inspect logs and confirm that /health and /api/* routes respond correctly:

vercel logs <deployment-url>

5. Submit the Manifest URL

Navigate to the OpenAI developer console and submit your production manifest URL. Upon successful validation of the endpoints and TLS configuration, the plugin becomes discoverable in ChatGPT.

Required Endpoints and Configuration

Every OpenAI plugin must implement specific HTTP endpoints and configuration files to pass marketplace validation.

Minimal Plugin Manifest

The following plugin.json structure provides the minimum required metadata:

{
  "schema_version": "v1",
  "name_for_human": "My Sample Plugin",
  "description_for_human": "A simple demo that echoes back user input.",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "https://my-plugin.vercel.app/openapi.yaml"
  },
  "logo_url": "https://my-plugin.vercel.app/logo.png",
  "contact_email": "[email protected]",
  "legal_info_url": "https://example.com/terms"
}

This structure mirrors the production implementation found in plugins/zoom/.codex-plugin/plugin.json.

Health Check Endpoint

The marketplace requires a /health endpoint that returns a success status. Here is a minimal Node.js/Express implementation:

const express = require('express');
const app = express();

app.get('/health', (_, res) => res.send('OK'));

app.listen(3000, () => console.log('Plugin running on port 3000'));

Similar patterns appear in the Zoom plugin's meeting SDK deployment guide at plugins/zoom/skills/meeting-sdk/windows/references/deployment.md.

Architectural Considerations

When deploying OpenAI plugins, adhere to these architectural patterns defined in the source repository:

• Stateless Runtime: Each HTTP request is isolated, permitting horizontal scaling on serverless platforms. Do not assume in-memory state persists between requests.
• Environment Variables: Sensitive values like OPENAI_API_KEY are injected by the host platform (Vercel's Environment UI) and must never be checked into source control per the repository's security policy.
• Multi-Region Support: For global deployments, configure multiple subdomains and list them in the manifest's baseUrl field. The marketplace selects the nearest endpoint based on the user's region.

Summary

• OpenAI plugins require a plugin.json manifest placed in .codex-plugin/ that defines the API specification and authentication model.
• Deploy to serverless platforms like Vercel, AWS Lambda, or Azure Functions, ensuring environment variables are configured externally.
• The marketplace validates the /health and /api/info endpoints before publication; these must return valid responses.
• Use the Vercel CLI (vercel for preview, vercel --prod for production) to deploy, as documented in plugins/vercel/skills/deployments-cicd/SKILL.md.
• Submit the live manifest URL through the OpenAI developer console to complete the deployment process.

Frequently Asked Questions

What file structure is required for an OpenAI plugin?

You must create a .codex-plugin/ directory containing plugin.json, along with your runtime code and a top-level README.md. The manifest specifies your plugin's metadata and API endpoints, while skill definitions typically reside in skills/ subdirectories as markdown files.

Which platforms can host OpenAI plugins?

While the openai/plugins repository provides examples for Vercel, you can deploy to any platform that supports HTTP endpoints and environment variable injection, including AWS Lambda, Azure Functions, Google Cloud Run, or traditional Docker containers. The key requirement is that the platform can serve the endpoints listed in your manifest's api section.

How does the marketplace validate a plugin before publication?

The marketplace fetches your manifest URL, validates the JSON schema, checks TLS configuration, and performs health checks against the /health and /api/info endpoints. It also verifies that the OpenAPI specification referenced in your manifest is accessible and syntactically valid.

Can I deploy the same plugin to multiple regions?

Yes. Configure separate subdomains for each region and list multiple baseUrl values in your manifest. The OpenAI Plugin Marketplace automatically routes users to the nearest geographic endpoint, improving latency for global deployments.

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