# Difference Between .app.json and .codex-plugin/plugin.json in OpenAI Plugins

> Understand the difference between .app.json and .codex-plugin/plugin.json for OpenAI plugins. Learn how these files manage UI metadata, identity, and runtime backend app ID mapping for request routing.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-06-29

---

**The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file provides the full declarative UI metadata and identity for OpenAI plugins, while [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) supplies the runtime backend app ID mapping used for request routing.**

In the OpenAI Plugins repository, each plugin follows a strict two-file configuration pattern that separates user-facing metadata from backend identifiers. Understanding the difference between [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) and [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) is essential for developers building plugins for the Codex platform.

## What is [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)?

This file lives in the `.codex-plugin/` directory within each plugin folder (e.g., [`plugins/fyxer/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.codex-plugin/plugin.json)). It serves as the **declarative manifest** that Codex consumes to render the plugin in the marketplace and UI.

### Declarative Metadata Structure

The file defines top-level identity fields including `name`, `version`, `description`, `author`, `repository`, `license`, and `keywords`. Crucially, it contains an `apps` field that points to the companion [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file, establishing the link between UI description and runtime configuration. According to the source in [`plugins/fyxer/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.codex-plugin/plugin.json), this field uses a relative path like `"./.app.json"`.

### The Interface Object

The heart of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) is the **`interface`** object. This contains UI-specific data such as `displayName`, `shortDescription`, `longDescription`, `websiteURL`, `privacyPolicyURL`, `termsOfServiceURL`, and icon paths (`composerIcon`, `logo`). This structure tells the platform exactly how the plugin should appear to users, including default prompts and branding assets.

## What is [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)?

Located at the plugin root (e.g., [`plugins/fyxer/.app.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.app.json)), this file provides the **runtime-only mapping** between the plugin's logical name and its backend-assigned identifier.

### Runtime App Identifier

The structure follows `{ "apps": { "<plugin-name>": { "id": "<app-id>" } } }`. For example, in [`plugins/fyxer/.app.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.app.json), the mapping contains `"id": "asdk_app_696e3c8854748191a6006dd80660ad35"`. This UUID-like string is opaque to the UI and used exclusively by the plugin host to route requests to the correct backend endpoints.

### Backend Integration

Unlike [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json), [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) contains no presentation logic. It is read by the plugin host during initialization to resolve the concrete app ID. This file may be regenerated automatically when the app is registered, making it a purely operational configuration rather than a source of truth for plugin metadata.

## Key Differences Between the Configuration Files

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)**: Defines **what the plugin is** and **how it should be presented**. Contains UI metadata, descriptions, icons, and user-facing configuration consumed by Codex.
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)**: Defines **how the plugin is identified** for backend operations. Contains only the runtime app ID used for request routing and service discovery.

The separation enables frontend teams to modify UI copy and icons without touching backend identifiers, while platform engineers can rotate or update app IDs without affecting the user experience.

## Practical Implementation Examples

### Minimal [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) Configuration

```json
{
  "name": "example-plugin",
  "version": "1.0.0",
  "description": "A simple example plugin.",
  "author": { "name": "Example Inc", "url": "https://example.com" },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Example Plugin",
    "shortDescription": "Shows the structural split.",
    "longDescription": "This plugin demonstrates the separation of UI metadata from runtime IDs.",
    "websiteURL": "https://example.com",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png"
  }
}

```

### Minimal [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) Configuration

```json
{
  "apps": {
    "example-plugin": {
      "id": "asdk_app_1234567890abcdef"
    }
  }
}

```

### Accessing the Runtime ID in Node.js

```javascript
const fs = require('fs');
const path = require('path');

const appConfig = JSON.parse(
  fs.readFileSync(path.join(__dirname, '.app.json'), 'utf8')
);

const pluginId = appConfig.apps['example-plugin'].id;
console.log(`Runtime app ID: ${pluginId}`);

```

## Summary

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** provides the full declarative description including UI metadata, icons, and user-facing text consumed by Codex.
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** supplies the runtime mapping between the plugin name and the backend-assigned app ID used for request routing.
- The `apps` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) points to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), linking the UI configuration to the runtime identifier.
- Files like [`plugins/fyxer/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.codex-plugin/plugin.json) and [`plugins/fyxer/.app.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.app.json) demonstrate this separation of concerns in the OpenAI Plugins repository.

## Frequently Asked Questions

### Can I modify [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) manually?

While technically possible, manual edits to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) are discouraged because this file is typically auto-generated when the plugin is registered with the backend. The `id` field contains backend-assigned identifiers that may change during re-registration or environment switches.

### What happens if the `apps` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) points to the wrong file?

Codex will fail to resolve the plugin's runtime configuration, causing the plugin to be unavailable for invocation. The `apps` field must correctly reference the relative path to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) (e.g., `"./.app.json"`) to maintain the link between UI metadata and backend identity.

### Why are these configurations split into two files?

The separation follows the architectural principle of dividing **presentation** from **implementation**. By isolating UI metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and runtime IDs in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), teams can update marketplace descriptions and icons without redeploying backend services, and vice versa.

### Where can I find real-world examples of these files?

Reference the OpenAI Plugins repository at `openai/plugins`. The `plugins/fyxer/` and `plugins/demandbase/` directories contain complete implementations showing the relationship between [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json).