Core Components of the OpenWork Architecture

The OpenWork architecture comprises five core components: an Electron-based Desktop client, the OpenWork Den control plane server, a Model Capability Provider (MCP) protocol layer, declarative Skills and Plugin systems, and shared Core Packages (@openwork/client, @openwork/server, etc.) that bind the system together.

The different-ai/openwork repository implements a modular, agent-first platform designed to run AI-driven workflows both locally and remotely. Its architecture intentionally separates the native user interface, centralized team management, and protocol interfaces to enable flexible deployment across individual workstations and enterprise teams.

OpenWork Desktop: The Electron Frontend

The OpenWork Desktop provides the native client application for macOS, Windows, and Linux. Located in the apps/ directory, this Electron-based runtime hosts a Chromium and Node.js environment that renders the UI, loads local skills, and establishes connections to MCP servers.

According to the repository README, the Desktop application handles local execution of skills and plugins while providing development profiles accessible via pnpm dev or pnpm dev:worktree. These commands initialize the Electron runtime with mock keychain authentication and expose a Chrome DevTools Protocol (CDP) endpoint for debugging.

OpenWork Den: The Control Plane Server

OpenWork Den operates as the centralized control plane for team management, model provider quotas, and policy enforcement. As documented in AGENTS.md, the Den functions as a SaaS-style service that coordinates skill marketplace distribution and authenticates remote requests from Desktop clients.

The Den exposes HTTP endpoints at https://api.openworklabs.com/mcp/agent that allow Desktop instances to synchronize skill definitions and retrieve organizational policies. This architecture enables collaborative workflows where skills are authored locally, published to the Den marketplace, and shared across team members.

MCP Layer: Model Capability Provider Protocol

The MCP (Model Capability Provider) layer implements a lightweight protocol that exposes skills, plugins, and remote model endpoints to compatible AI agents including Claude Code, Codex, and Cursor. This protocol layer decouples skill definitions from execution environments, allowing external agents to invoke capabilities without requiring local Desktop installation.

The MCP server supports the search_capabilities method for discovery and execute_capability for remote invocation. These interfaces enable the Den to act as a capability broker while the Desktop handles local execution, creating a hybrid local-first, cloud-ready architecture.

Skills System and Plugin Architecture

Skills are declarative assets defined in YAML or JSON that specify input schemas, execution runtimes, and UI hooks. Each skill definition located in the packages/ workspace includes an input_schema object and an implementation block pointing to entrypoint code, allowing the Desktop to render appropriate UI components and the Den to index capabilities.

Plugins extend the Desktop client with custom TypeScript or JavaScript functionality. Both skills and plugins are configured through warden.toml, which declares active components, policy settings, and MCP connection parameters for specific runtime environments.

Core Packages and Workspace Structure

The packages/ directory contains Core Packages that provide shared functionality across the architecture:

• @openwork/client: Client-side libraries for Desktop application integration
• @openwork/server: Server-side utilities for the Den control plane
• @openwork/mcp-client: Protocol implementation for MCP capability discovery and execution

The warden.toml configuration file at the repository root orchestrates these packages by defining skill registries, plugin loading order, and MCP endpoint settings. This configuration-driven approach ensures consistent behavior across development, staging, and production profiles.

Implementation Examples

Configuring MCP Client Access

To connect an AI agent to the OpenWork MCP layer, define the remote endpoint in your client configuration:

{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

This configuration enables capability discovery and authenticated skill execution through the Den infrastructure.

Querying Capabilities with the MCP Client

Use the @openwork/mcp-client package to discover available skills programmatically:

import { createMcpClient } from '@openwork/mcp-client';

const client = createMcpClient('https://api.openworklabs.com/mcp/agent');

async function listCapabilities() {
  const caps = await client.search_capabilities({});
  console.log('Available capabilities:', caps);
}

listCapabilities();

The search_capabilities method returns indexed skills from both local packages and the Den marketplace.

Defining a Skill Manifest

Create a skill.yaml file within the packages/ workspace to declare a new capability:

name: hello-world
description: Returns a friendly greeting
input_schema:
  type: object
  properties:
    name:
      type: string
      description: Name of the person to greet
  required: [name]
implementation:
  runtime: node
  entrypoint: src/index.ts

This manifest allows the Desktop to validate inputs and the Den to register the skill in the team marketplace.

Launching Development Environments

Initialize the Desktop application with specific development profiles:

# Start with default mock keychain and isolated profile

pnpm dev:worktree

# Or specify a named profile for feature testing

OPENWORK_DEV_PROFILE=my-feature pnpm dev

The terminal output confirms initialization with the active profile and CDP debugging endpoint (e.g., cdp=http://127.0.0.1:9223).

Summary

• OpenWork Desktop: Electron-based frontend in apps/ providing native UI, skill execution, and plugin hosting
• OpenWork Den: Control plane server managing team authentication, quotas, and the skill marketplace
• MCP Layer: Protocol interface in @openwork/mcp-client enabling AI agents to discover and execute capabilities via search_capabilities and execute_capability
• Skills System: Declarative YAML/JSON definitions in packages/ standardizing AI capability inputs and execution parameters
• Plugin Architecture: Extension system for custom Desktop functionality configured through warden.toml
• Core Packages: Shared libraries (@openwork/client, @openwork/server) unifying the architecture across the monorepo workspace

Frequently Asked Questions

How do the Desktop client and Den interact in the OpenWork architecture?

The Desktop client operates as the local execution environment while the Den serves as the centralized coordination layer. The Desktop authenticates against the Den via OAuth to synchronize skill definitions, download team policies, and report usage metrics, enabling both offline-local work and online collaboration within the same workflow.

What is the role of the MCP protocol in OpenWork?

The MCP protocol acts as the interoperability layer that exposes OpenWork skills to external AI agents such as Claude Code and Cursor. Implemented in @openwork/mcp-client, it provides standardized methods including search_capabilities for discovery and execute_capability for invocation, allowing remote agents to utilize OpenWork skills without running the Desktop application.

Where are skill definitions stored and how are they loaded?

Skill definitions are stored as YAML manifests within the packages/ directory of the different-ai/openwork repository. The Desktop loads these from the local workspace during development, while the Den indexes them for marketplace distribution. The warden.toml configuration file specifies which skills are active in a given runtime profile.

How does warden.toml configure the OpenWork architecture?

The warden.toml file at the repository root declares runtime profiles, skill registries, plugin activation states, and MCP connection settings. It controls policy-level behavior such as mock keychain usage, profile isolation, and endpoint URLs, ensuring consistent component initialization across development and production environments.

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