# OpenWork Plugin Distribution Model: How Marketplace Plugins Are Delivered via the Cloud

> Discover how OpenWork distributes marketplace plugins via the cloud. Access and execute plugins directly from the Den database using search and execute endpoints for seamless integration.

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

---

**OpenWork distributes marketplace plugins as cloud-delivered capabilities stored in the Den database, enabling agents to discover and execute them through the existing `search_capabilities` and `execute_capability` endpoints without requiring local installation.**

The `different-ai/openwork` repository implements a cloud-first **plugin distribution model** that treats marketplace extensions as searchable capability records rather than traditional downloadable packages. This architecture allows members to use plugin functionality on demand via database-driven lookups while maintaining an optional offline installation path for specific scenarios.

## Database Storage Architecture in the Den Schema

OpenWork persists plugins and their associated metadata within the Den database using a dedicated schema defined in [`ee/packages/den-db/src/schema/sharables/plugin-arch.ts`](https://github.com/different-ai/openwork/blob/main/ee/packages/den-db/src/schema/sharables/plugin-arch.ts). The storage layer utilizes several interconnected tables to manage the complete plugin lifecycle:

- **`plugin`** – Stores core plugin metadata and source definitions
- **`marketplace`** – Defines marketplace boundaries and organizational scopes
- **`marketplace_plugin`** – Links plugins to specific marketplaces with version constraints
- **`plugin_config_object`** – Contains configurable skill definitions and parameter schemas
- **`plugin_access_grant`** and **`marketplace_access_grant`** – Implement the grant cascade for access control

This relational approach ensures that plugin content, configuration objects, and access permissions are queryable via standard SQL joins, eliminating the need for external network calls during capability discovery.

## Discovery Through the Capability Search Pipeline

When an agent invokes `search_capabilities`, the system merges **marketplace plugin capabilities** as a fourth capability source alongside internal tools, custom capabilities, and external MCP connections. This merge operation occurs entirely within the database layer in [`ee/apps/den-api/src/mcp/marketplace-capabilities.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/mcp/marketplace-capabilities.ts).

The integration point in [`ee/apps/den-api/src/mcp/agent.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/mcp/agent.ts) combines these sources while respecting the same **grant cascade** used for other organizational resources. The system evaluates org-wide, team-specific, and individual member grants to determine visibility, ensuring that marketplace plugins appear alongside native capabilities when permissions allow. Because this search is purely DB-driven, results return with the same latency characteristics as local capability queries.

## Execution Model and Instructional Payloads

The `execute_capability` endpoint processes marketplace requests using a specialized naming convention: `plugin:<pluginId>:<configObjectId>`. When receiving such a request, the implementation in [`ee/apps/den-api/src/mcp/marketplace-capabilities.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/mcp/marketplace-capabilities.ts) performs the following sequence:

1. **Version Resolution** – Loads the latest version of the requested config object via `config_object_version` tracking
2. **Grant Verification** – Validates the requesting member's access rights against `plugin_access_grant` records
3. **Payload Generation** – Returns an **instructional payload** containing the raw source text, provenance information, and operational hints

The response payload includes structured fields such as `kind`, `content` (the markdown source), and status indicators like `needs_install` for tools requiring local execution environments. Critically, **no code executes on the server**; the payload is designed for consumption by the agent runtime or display in the desktop UI, mirroring the existing external MCP connection flow.

## Optional Local Installation for Offline Use

While the default distribution flow keeps plugin content in the cloud, OpenWork supports optional local installation into `.opencode/` as an optimization for offline use or version pinning. The standard cloud flow follows this pattern:

```typescript
// Agent discovers available capabilities
await agent.runTool("search_capabilities", {
  query: "summarize meeting notes",
  limit: 5
});

// Result includes marketplace matches like:
// { name: "plugin:meeting-summarizer:skill-42", method: "PLUGIN", ... }

// Agent executes without local installation
await agent.runTool("execute_capability", {
  name: "plugin:meeting-summarizer:skill-42"
});

// Returns instructional payload:
/*
{
  "kind": "skill",
  "plugin": "Meeting Summarizer",
  "name": "Summarize Meeting Notes",
  "content": "...skill markdown source...",
  "provenance": "Content from marketplace plugin Meeting Summarizer in your organization's library.",
  "status": { "needs_install": false }
}
*/

```

For scenarios requiring local copies, the desktop application invokes the install flow defined in [`apps/server/src/cloud-plugins.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-plugins.ts), which copies plugin files from the cloud store into the local `.opencode/` directory while maintaining the same capability identity.

## Organizational Control and Security Gates

OpenWork provides an **organization-level kill switch** that disables marketplace functionality entirely. The `metadata.capabilities.mcpConnections` flag, which gates external MCP connections, simultaneously disables marketplace capability search and execution. Organizations that opt out maintain byte-identical behavior with marketplace features completely suppressed, ensuring consistent runtime characteristics across different security postures.

## Distribution Roadmap and Evolution

The **plugin distribution model** evolves through three defined phases:

- **Phase 1 (Current)** – Database-only search with instructional execution and optional local install
- **Phase 2** – Pre-compiled capability records at publish time, versioned record immutability, and MCP specification bridging
- **Phase 3** – Removal of the local copy requirement entirely, transitioning to sandboxed cloud execution environments

This roadmap maintains backward compatibility while progressively reducing client-side dependencies.

## Summary

- OpenWork delivers marketplace plugins as **cloud-stored capability records** within the Den database, not as traditional downloadable artifacts
- The `search_capabilities` endpoint treats marketplace plugins as a **fourth capability source**, merging them database-side with zero network overhead
- **Execution** occurs via `execute_capability` using the `plugin:<pluginId>:<configObjectId>` naming convention, returning instructional payloads rather than executing code server-side
- **Local installation** into `.opencode/` remains optional, handled by [`apps/server/src/cloud-plugins.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-plugins.ts), and serves only as an offline optimization
- Organizations can **disable marketplace access** entirely using the `metadata.capabilities.mcpConnections` flag, ensuring consistent runtime behavior for security-sensitive environments

## Frequently Asked Questions

### How does OpenWork's plugin distribution model differ from traditional package managers?

Traditional package managers require downloading and installing code locally before execution, whereas OpenWork's model serves plugin content as **instructional payloads** from the cloud on demand. Agents receive capability definitions via the `search_capabilities` and `execute_capability` endpoints without requiring pre-installation, though [`apps/server/src/cloud-plugins.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-plugins.ts) provides an optional local copy mechanism for offline scenarios.

### What happens when an agent executes a marketplace plugin capability?

The `execute_capability` endpoint parses the `plugin:<pluginId>:<configObjectId>` name format, validates the member's grants against `plugin_access_grant` records, and returns a JSON payload containing the skill's source text, provenance metadata, and execution hints. No code runs on OpenWork's servers; the agent or desktop client consumes this payload to perform the actual operation.

### Can organizations restrict access to marketplace plugins?

Yes. Organizations can disable marketplace functionality by setting the `metadata.capabilities.mcpConnections` flag to false. This acts as a kill switch that removes marketplace capabilities from `search_capabilities` results and blocks `execute_capability` calls for plugin names, providing byte-identical behavior for security-constrained environments.

### Is local installation required to use OpenWork marketplace plugins?

No. Local installation into `.opencode/` is strictly optional and serves only as an optimization for offline use or version pinning. The default flow retrieves plugin content directly from the Den database tables defined in [`ee/packages/den-db/src/schema/sharables/plugin-arch.ts`](https://github.com/different-ai/openwork/blob/main/ee/packages/den-db/src/schema/sharables/plugin-arch.ts) during the `execute_capability` call, enabling immediate use without filesystem writes.