What Are the Core Components of OpenWork? A Complete Architecture Guide

OpenWork is a monorepo-based platform composed of a desktop Electron client, a cloud-first Den server, reusable UI libraries, and modular AI skills that integrate via MCP.

This guide breaks down the architecture of different-ai/openwork, an open-source framework for building AI-powered workflows. Understanding these core components helps developers deploy, extend, and customize OpenWork for local-first or enterprise-scale use cases.

Desktop Client: The Local-First Entry Point

The desktop client is an Electron application that provides native macOS, Windows, and Linux support while hosting a local CDP (Chrome DevTools Protocol) server for agent integration.

• Source location: apps/desktop/
• Entry point: apps/desktop/main.ts

# Start the desktop client

pnpm dev

# Run multiple isolated instances (for testing)

pnpm dev:worktree

The main.ts file bootstraps the Electron process, window management, and the embedded CDP server. This local-first approach ensures sensitive data stays on-device while still enabling agent automation.

Den Server: The Cloud Control Plane

OpenWork Den is the server-side API that handles multi-tenancy, model provider configuration, and skill publishing. It serves as the control plane for teams needing centralized management.

• Source location: apps/server/
• Entry point: apps/server/src/index.ts

# Start Den with local MySQL and web UI

pnpm dev:den

This command executes scripts/dev-local.mjs, which orchestrates Docker Compose (packaging/docker/docker-compose.web-local.yml) before launching the Express-based server. The Den server stores organizations, teams, and MCP configurations in a relational database.

Core UI Library: Shared React Components

The @openwork/ui package provides a shadcn-style component library used by both desktop and web interfaces. Centralizing UI code ensures consistency across deployment targets.

• Source location: packages/ui/
• Export hub: packages/ui/src/react/index.ts

import { Button } from '@openwork/ui/react'

export default function Example() {
  return (
    <Button onClick={() => console.log('OpenWork action')}>
      Trigger Workflow
    </Button>
  )
}

The package's package.json uses conditional exports to support both React and potential future framework targets.

MCP Client: Agent Integration Layer

The openwork-ui-mcp package implements the Model Context Protocol (MCP), allowing external AI agents (Claude Code, Cursor, etc.) to invoke OpenWork capabilities.

• Source location: packages/openwork-ui-mcp/
• Entry point: packages/openwork-ui-mcp/src/index.ts

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

After configuration, agents gain access to search_capabilities and execute_capability methods, bridging local tools with cloud-hosted skills.

Hands-Free Layer: Voice-Driven Automation

The handsfree package adds speech-to-text and command routing for voice-controlled agent interactions.

• Source location: packages/handsfree/
• Entry point: packages/handsfree/src/index.ts

# Start the voice processing service

pnpm --filter @openwork/handsfree dev

This component parses spoken commands into structured agent instructions, enabling hands-free workflow execution.

Skill Packages: Modular Capabilities

OpenWork organizes functionality into reusable skill packages under packages/:

Package	Purpose
automations	Core automation primitives
connect-link	OAuth and connection management
enterprise-mcp-client	Enterprise MCP gateway
create-openwork-app	Project scaffolding CLI

Each skill follows a consistent structure with its own src/ directory, package.json, and entry point. This modularity lets developers import only needed capabilities.

Configuration and Tooling

Several root-level files govern the monorepo structure:

File	Function
package.json	Workspace scripts: pnpm dev, pnpm dev:den, pnpm dev:worktree
warden.toml	OpenWork-specific workspace configuration
AGENTS.md	Architecture philosophy and agent integration patterns
scripts/dev-local.mjs	Docker orchestration and development server bootstrap

The root package.json defines the workspace glob pattern, letting pnpm resolve cross-package dependencies automatically.

Summary

• Desktop client (apps/desktop/) delivers local-first, native application experience with embedded agent server
• Den server (apps/server/) provides cloud-scale multi-tenancy and skill management
• UI library (packages/ui/) shares React components across deployment targets
• MCP client (packages/openwork-ui-mcp/) standardizes external AI agent integration
• Hands-free layer (packages/handsfree/) enables voice-driven interactions
• Skill packages (packages/*) offer modular, composable capabilities
• Configuration files at repository root tie the monorepo together with warden.toml and npm scripts

Frequently Asked Questions

What is the difference between OpenWork Desktop and Den?

OpenWork Desktop runs locally as an Electron app—ideal for individual users who want data to stay on their machine. OpenWork Den is a server deployment for teams needing shared workspaces, centralized model configuration, and multi-user access. Both use identical skill packages and UI components.

How do external AI agents connect to OpenWork?

Agents connect via the MCP client defined in packages/openwork-ui-mcp/. Developers add a remote MCP configuration pointing to https://api.openworklabs.com/mcp/agent, then agents can discover and execute capabilities through standardized search_capabilities and execute_capability calls.

Can I run OpenWork without the cloud server?

Yes. The desktop client operates entirely local-first. The CDP server embedded in apps/desktop/main.ts allows agents to interact with OpenWork without any external API calls. Cloud features are opt-in via Den deployment.

What package manager does OpenWork use?

OpenWork uses pnpm with workspace configuration defined in the root package.json. Commands like pnpm dev, pnpm dev:den, and pnpm --filter @openwork/handsfree dev leverage pnpm's filtering and hoist patterns for efficient monorepo management.

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