# Understanding the CLAUDEPLUGINDATA Environment Variable in OpenAI Codex Plugin CC

> Learn about the CLAUDEPLUGINDATA environment variable. It provides a Base64 encoded JSON manifest to the Codex plugin, simplifying configuration for serverless and containerized apps.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-18

---

**The CLAUDEPLUGINDATA environment variable supplies a Base64-encoded JSON manifest to the Codex plugin at startup, eliminating the need for external configuration files in serverless and containerized deployments.**

The `openai/codex-plugin-cc` repository uses this environment variable to pass the Claude-compatible plugin manifest directly to the runtime. When the plugin process initializes, it reads this variable to register the plugin's endpoints, authentication methods, and tool definitions with the Claude API framework.

## What CLAUDEPLUGINDATA Contains

The variable stores a **Base64-encoded JSON string** representing the complete plugin manifest. This manifest describes:

- The plugin's **name**, **description**, and **version**
- **HTTP endpoints** that Claude may invoke (GET/POST routes with request/response schemas)
- **Authentication configuration** (API keys, bearer tokens, or other security schemes)
- Additional **tool definitions** available for Claude to call

By encoding this data into an environment variable, the plugin supports deployment scenarios where filesystem access is restricted or undesirable, such as AWS Lambda, Docker containers, or CI/CD pipelines.

## Implementation in the Source Code

According to the `openai/codex-plugin-cc` source code, the plugin reads `CLAUDEPLUGINDATA` during the initialization phase. In [`plugins/codex/scripts/lib/utils/environment.js`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/utils/environment.js), the runtime decodes and parses this variable to extract the manifest configuration.

The `loadClaudePluginData()` function handles this process:

```javascript
// plugins/codex/scripts/lib/utils/environment.js (simplified)
function loadClaudePluginData() {
  const encoded = process.env.CLAUDEPLUGINDATA;
  if (!encoded) {
    throw new Error('CLAUDEPLUGINDATA not set');
  }
  const json = Buffer.from(encoded, 'base64').toString('utf8');
  return JSON.parse(json);
}

// Initialization in main.js
const pluginManifest = loadClaudePluginData();
claude.registerPlugin(pluginManifest);

```

This pattern ensures the plugin fails fast with a clear error message if the required configuration is missing.

## Step-by-Step Deployment Workflow

Setting up the variable follows a four-step process:

1. **Generate** the plugin manifest as a JSON file following the Claude plugin specification
2. **Encode** the JSON content using Base64 encoding
3. **Export** the encoded string as the `CLAUDEPLUGINDATA` environment variable
4. **Launch** the plugin server, which automatically decodes and registers the manifest

### Practical Example

Create and encode a manifest:

```bash

# Create manifest.json

cat <<EOF > manifest.json
{
  "name": "MyPlugin",
  "description": "Demo plugin for Claude",
  "version": "1.0.0",
  "endpoints": [
    {
      "path": "/search",
      "method": "POST",
      "request": { "type": "object", "properties": { "query": { "type": "string" } } },
      "response": { "type": "object", "properties": { "results": { "type": "array" } } }
    }
  ]
}
EOF

# Encode and set environment variable

export CLAUDEPLUGINDATA=$(cat manifest.json | base64 -w0)

# Start the plugin

node ./plugins/codex/scripts/main.js

```

## Key Repository Files

The implementation spans several critical files:

- **[`plugins/codex/scripts/lib/utils/environment.js`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/utils/environment.js)**: Contains the `loadClaudePluginData()` function that reads and decodes the environment variable
- **[`plugins/codex/scripts/lib/auth/constants.js`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/auth/constants.js)**: Defines authentication-related constants referenced by the manifest parser
- **`dist/plugin.mjs`**: The compiled entry point that invokes the manifest loader during startup
- **[`test/plugin.test.js`](https://github.com/openai/codex-plugin-cc/blob/main/test/plugin.test.js)**: Unit tests verifying correct parsing of the environment variable

## Summary

- **CLAUDEPLUGINDATA** is a Base64-encoded JSON environment variable required by the `openai/codex-plugin-cc` runtime
- It replaces the need for a physical [`manifest.json`](https://github.com/openai/codex-plugin-cc/blob/main/manifest.json) file, enabling serverless deployments
- The `loadClaudePluginData()` function in [`environment.js`](https://github.com/openai/codex-plugin-cc/blob/main/environment.js) handles decoding and validation
- The manifest must conform to Claude's plugin specification, defining endpoints and authentication schemes

## Frequently Asked Questions

### What happens if CLAUDEPLUGINDATA is not set?

The plugin will throw an explicit error during startup. The `loadClaudePluginData()` function checks for the variable's presence and throws `'CLAUDEPLUGINDATA not set'` if it is missing or empty, preventing the server from starting in an unconfigured state.

### Why use Base64 encoding for the manifest?

Base64 encoding ensures the JSON manifest can be safely passed through environment variables without issues related to special characters, newlines, or shell interpretation. This encoding method preserves the exact byte sequence of the JSON configuration across different deployment platforms and shell environments.

### Can I use a regular manifest.json file instead?

While the `openai/codex-plugin-cc` repository is designed to prioritize the `CLAUDEPLUGINDATA` environment variable for flexibility, the implementation in [`plugins/codex/scripts/lib/utils/environment.js`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/utils/environment.js) specifically expects this variable. To use a file-based approach, you would need to modify the `loadClaudePluginData()` function to read from the filesystem and encode the contents before parsing.

### Where can I find the schema for the manifest JSON?

The manifest must follow the Claude plugin specification, which defines required fields such as `name`, `description`, `version`, and `endpoints`. The TypeScript definitions in [`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts) contain the interface definitions for the manifest structure expected by the runtime.