# OpenWork Extension Manifest Format: Complete Technical Reference

> Explore the OpenWork extension manifest format, detailing required fields like id, name, and source, plus optional configurations for UI and lifecycle. Learn the complete technical reference.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: api-reference
- Published: 2026-07-31

---

**The OpenWork extension manifest format is defined by the TypeScript interface `OpenWorkExtensionManifest` in [`apps/app/src/app/extensions.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/extensions.ts), which requires a `schemaVersion` of `1`, unique `id`, `name`, `description`, `source`, and `resources` fields, while supporting optional configurations for UI contributions, lifecycle management, and platform-specific enablement conditions.**

The `different-ai/openwork` repository implements a plugin architecture where every extension must conform to the strict **OpenWork extension manifest format**. This JSON-compatible contract enables the host application to dynamically register MCP servers, UI panels, and provider bindings through a declarative configuration object that the system validates, parses, and consumes at runtime.

## Core Manifest Structure

According to the source definition in [`apps/app/src/app/extensions.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/extensions.ts) (lines 109-158), every extension manifest must implement the `OpenWorkExtensionManifest` interface. The following fields are mandatory:

- **schemaVersion**: Must be the literal number `1`. This field ensures forward compatibility as the schema evolves.
- **id**: A unique string identifier (e.g., `"openwork-browser"`) used for internal references and dependency resolution.
- **name**: Human-readable title displayed in the OpenWork UI.
- **description**: Concise explanation of the extension's functionality and purpose.
- **source**: An `OpenWorkExtensionSource` object defining delivery mechanism (builtin, marketplace) and trust level.
- **resources**: An array of `OpenWorkExtensionResource` objects describing concrete assets such as MCP servers, secrets, or native binaries.

## Optional Configuration Properties

Beyond the required fields, the OpenWork extension manifest format supports extensive optional configuration to control visibility, runtime behavior, and user experience.

### UI Visibility and Branding

- **preview**: Boolean flag indicating experimental status. When `true`, the extension displays preview badges in the UI.
- **icon**: Optional object containing either a `src` URL or `simpleIconSlug` for built-in icon sets.
- **defaultHidden**: When `true`, the extension remains hidden from the UI unless explicitly revealed by the user.

### Runtime and Platform Constraints

- **platform**: Restricts execution to specific operating systems. Valid values include `"darwin"`, `"linux"`, `"windows"`, and `"web"`.
- **defaultEnabled**: Boolean determining whether the extension starts in an enabled state for new workspaces.
- **lifecycle**: An `OpenWorkExtensionLifecycle` object specifying when the host should reload (e.g., `["plugins", "agents"]`) and how to detect the extension's presence.
- **enablement**: An array of `EnablementCondition` objects that must all evaluate to true before the extension activates. Conditions include MCP connection status, environment variable presence, permission grants, and toggle states.

### User Experience Configuration

- **composer**: Object with a `prompt` string that populates the composer panel when the extension is invoked.
- **setup**: An `OpenWorkExtensionSetup` object containing instructions and call-to-action strings displayed during initial enablement.
- **contributions**: An array of `OpenWorkExtensionContribution` objects defining UI hooks such as settings panels, session side-panels, and custom routes.

## Supporting Type Definitions

The manifest format relies on several supporting types that define the extension's integration points.

### Source Configuration

The `OpenWorkExtensionSource` type, defined alongside the manifest interface, specifies how the extension is delivered to the host. It distinguishes between builtin extensions packaged with the application and marketplace extensions downloaded from remote sources, including trust level verification.

### Resources vs. Contributions

- **OpenWorkExtensionResource**: Enumerates concrete assets the extension provides, including MCP servers, provider bindings, secrets, and native binaries.
- **OpenWorkExtensionContribution**: Declares UI or server-side hooks that extend OpenWork's functionality, such as adding settings panels, composer prompts, or API routes.

## Practical Implementation Examples

### Minimal Valid Manifest

The following JSON represents the smallest valid OpenWork extension manifest, suitable for simple builtin extensions:

```json
{
  "schemaVersion": 1,
  "id": "example-extension",
  "name": "Example Extension",
  "description": "Demonstrates the minimal required fields.",
  "source": { "format": "openwork-builtin", "origin": "builtin", "trusted": true },
  "resources": [],
  "contributions": []
}

```

### Production-Grade Extension Configuration

This TypeScript example mirrors the built-in "OpenWork Browser" extension, demonstrating advanced features including lifecycle management, platform restrictions, and multiple contribution points:

```typescript
import type { OpenWorkExtensionManifest } from "./extensions";

export const browserExtension: OpenWorkExtensionManifest = {
  schemaVersion: 1,
  id: "openwork-browser",
  name: "OpenWork Browser",
  description: "Automate the built-in browser panel that stays visible inside OpenWork.",
  source: { format: "openwork-builtin", origin: "builtin", trusted: true },
  icon: { src: "/openwork-mark.svg" },
  composer: { prompt: "Use the OpenWork Browser extension to " },
  setup: { instructions: "OpenWork Browser is ready by default in desktop workspaces." },
  resources: [
    {
      type: "opencode-plugin",
      id: "opencode-chrome-devtools",
      packageName: "opencode-chrome-devtools",
      required: true,
    },
  ],
  contributions: [
    { type: "settings-panel", ref: "openwork.browser.settings", location: "settings-detail" },
    { type: "session-side-panel", ref: "openwork.browser.panel", location: "session-right-pane" },
    { type: "composer-prompt", prompt: "Use the OpenWork Browser extension to ", location: "composer" },
  ],
  enablement: [{ type: "toggle-enabled", ref: "openwork-browser", label: "Enabled" }],
  lifecycle: {
    reload: ["plugins", "agents"],
    detection: ["plugin:opencode-chrome-devtools"],
  },
  defaultEnabled: true,
  platform: ["darwin", "linux", "windows"],
};

```

## Schema Validation and Parsing

The OpenWork codebase implements multiple validation layers to ensure manifest integrity across different contexts:

- **Type Definitions**: The canonical interface in [`apps/app/src/app/extensions.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/extensions.ts) provides compile-time type safety for TypeScript consumers.
- **Runtime Parsing**: The `parseOpenWorkExtensionManifest` function in [`apps/app/src/app/lib/den.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/den.ts) transforms raw JSON into typed manifest objects.
- **API Validation**: The Zod schema in [`ee/apps/den-api/src/routes/org/plugin-system/schemas.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/routes/org/plugin-system/schemas.ts) validates marketplace payloads before persistence.
- **UI Integration**: Utilities in [`apps/app/src/app/constants.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/constants.ts) convert manifest data into directory information for the user interface.

## Summary

- The **OpenWork extension manifest format** requires `schemaVersion: 1`, unique `id`, `name`, `description`, `source`, and `resources` fields for all extensions.
- Optional fields control **platform restrictions**, **lifecycle reloading**, **enablement conditions**, and **UI contributions** through declarative configuration.
- The `OpenWorkExtensionManifest` interface in [`apps/app/src/app/extensions.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/extensions.ts) serves as the single source of truth, validated at runtime by parsers in [`apps/app/src/app/lib/den.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/den.ts) and API schemas in [`ee/apps/den-api/src/routes/org/plugin-system/schemas.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/routes/org/plugin-system/schemas.ts).
- Extensions can declare **resources** (MCP servers, binaries) and **contributions** (UI panels, routes) to extend both backend functionality and frontend interfaces.

## Frequently Asked Questions

### What is the current schemaVersion for OpenWork manifests?

The current OpenWork extension manifest format requires `schemaVersion` to be the literal number `1`. This field exists for future-proofing, allowing the host application to handle schema migrations as the platform evolves.

### How does OpenWork validate extension manifests?

Validation occurs at multiple stages: TypeScript provides compile-time checking against the `OpenWorkExtensionManifest` interface, the `parseOpenWorkExtensionManifest` function in [`apps/app/src/app/lib/den.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/app/lib/den.ts) handles runtime JSON parsing, and the Zod schemas in [`ee/apps/den-api/src/routes/org/plugin-system/schemas.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/routes/org/plugin-system/schemas.ts) enforce structure for marketplace submissions.

### Can an extension be restricted to specific operating systems?

Yes, the optional `platform` field accepts an array of strings including `"darwin"`, `"linux"`, `"windows"`, and `"web"`. When specified, the extension only loads on matching platforms, allowing native binaries to target specific operating systems while excluding incompatible environments.

### What is the difference between resources and contributions in an OpenWork manifest?

**Resources** are concrete assets the extension provides, such as MCP servers, secrets, or native binaries. **Contributions** are UI or server-side integration points, such as settings panels, side-panels, or API routes, that extend the host application's functionality without requiring separate asset deployment.