# different‑ai/openwork Architecture Explained: A Deep Dive into the Modular AI‑Assistant Platform

> Explore the different-ai/openwork architecture, a modular AI-assistant platform. Understand its core components: Electron client, local workspace server, and optional remote control plane.

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

---

**The different‑ai/openwork architecture is a modular, client‑first platform built on an Electron desktop client, a local workspace server, and an optional remote OpenWork Den control plane connected via the Message Capability Protocol (MCP).**

OpenWork (`different‑ai/openwork`) is designed to run as a **local‑first AI assistant** that can optionally extend into team‑wide cloud infrastructure. Its architecture separates concerns across distinct layers—from the native UI down to skill definitions—enabling both offline productivity and seamless multi‑agent collaboration.

## The Five Core Layers of OpenWork

### Electron Desktop Client: The Native Interface

The **desktop client** provides the cross‑platform UI and the runtime environment for executing OpenWork capabilities. It is built on Electron and bundles a Vite‑powered development server for hot‑reloading during local development.

- **Entry point**: `apps/desktop/` (Electron main process and renderer)
- **Build tooling**: [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) pipelines orchestrate the client build alongside other packages

When you run `pnpm dev`, the client boots and prints its profile and Chrome DevTools Protocol (CDP) endpoint:

```bash
pnpm dev

# [openwork] dev profile=/home/user/.openwork/worktrees/main cdp=http://127.0.0.1:9223

```

The `OPENWORK_DEV_PROFILE` environment variable, derived from the worktree path, isolates development state per checkout.

### Local Workspace Server: MCP at the Core

Every OpenWork client runs an **embedded HTTP server** that manages:

- File‑system workspace state
- User settings and cached credentials
- The **OpenWork MCP (Message Capability Protocol) endpoint**

The local server implements the MCP specification defined in `packages/mcp/`, exposing capabilities that any attached agent can discover and invoke. This server is started automatically by the desktop client and listens on a local port.

Key directories:
- `packages/workspace/` — workspace management and file operations
- `packages/mcp/` — MCP protocol implementation

### OpenWork Den: Optional Cloud Control Plane

**OpenWork Den** is the remote, multi‑tenant service that provides:

- Organization‑wide configuration
- Model provider credentials and routing
- Centralized skill marketplace
- Policy enforcement and audit logging

When Den is enabled, the local MCP forwards authenticated requests to `https://api.openworklabs.com/mcp/agent`. The desktop client connects transparently—skills remain accessible through the same `search_capabilities` and `execute_capability` calls regardless of whether they are local or remote.

- **Implementation**: `apps/den/`

### Skills and Warden: Declarative Capabilities

Capabilities in OpenWork are **declarative, versioned definitions** stored in the `.warden/skills/` directory. Each skill is a JSON or YAML file describing:

- Input/output schemas
- Execution environment (local shell, remote API, UI widget)
- Metadata for discoverability

The **Warden runtime** loads these definitions at startup and registers them with the MCP. Agents query capabilities through a unified interface without needing to know implementation details.

```typescript
// Discover capabilities from a connected OpenWork client
import { search_capabilities } from 'openwork-mcp-client';

const caps = await search_capabilities({ query: 'summarize' });
// Returns: [{ capabilityId: 'summarize_document', ... }]

```

### OpenCode Integration: Universal Agent Compatibility

OpenWork exposes its full capability surface to **any OpenCode‑compatible agent** (Claude Code, Cursor, Codex, etc.) through a configuration file. The [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) at the repository root registers OpenWork as a remote MCP server:

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

```

This bridges OpenWork’s local capabilities into external tools without code changes.

## Data Flow: From User Action to Capability Execution

1. **Bootstrap**: Electron starts → local workspace server initializes → skills load from `.warden/skills/`
2. **Discovery**: Agent calls `search_capabilities` via MCP → Warden returns matching skill definitions
3. **Execution**: Agent calls `execute_capability` with arguments → local server resolves handler (local function or remote Den proxy)
4. **Response**: Result streams back through MCP → agent receives structured output

## Monorepo Structure and Build System

OpenWork uses **pnpm workspaces** with the following conventions:

| File | Purpose |
|------|---------|
| [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) | Defines workspace packages (`apps/*`, `packages/*`) |
| [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) | Task pipelines for build, test, and dev orchestration |
| `packages/ui/` | Shared shadcn/ui components across applications |

This structure lets developers run `pnpm dev` from the root to start all interconnected services simultaneously.

## Summary

- **Client layer**: Electron desktop app with embedded Vite dev server (`apps/desktop/`)
- **Server layer**: Local MCP‑enabled workspace server (`packages/workspace/`, `packages/mcp/`)
- **Cloud layer**: Optional OpenWork Den for team‑wide governance (`apps/den/`)
- **Capability layer**: Declarative skills managed by Warden (`.warden/skills/`)
- **Integration layer**: OpenCode MCP bridge ([`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json))

## Frequently Asked Questions

### How does OpenWork handle offline usage?

The desktop client runs a **complete local stack**: Electron UI, workspace server, and embedded MCP. Skills stored in `.warden/skills/` execute without network access. Cloud features are strictly optional and degrade gracefully—local capabilities remain fully functional.

### What is the Message Capability Protocol (MCP) in OpenWork?

MCP is OpenWork's **standardized capability‑discovery and execution protocol**. Defined in `packages/mcp/`, it provides `search_capabilities` and `execute_capability` endpoints that any agent can consume. The protocol abstracts whether a capability runs locally or proxies to OpenWork Den.

### Can I extend OpenWork with custom skills?

Yes. Add a JSON or YAML file to `.warden/skills/` following the Warden schema. The server hot‑reloads definitions and registers them with the MCP automatically. Skills can shell out to local binaries, call remote APIs, or render custom UI components.

### How do external agents connect to a running OpenWork instance?

External agents use the **OpenCode configuration** in [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json). Point the MCP URL to your local server (`http://localhost:<port>/mcp`) for development or `https://api.openworklabs.com/mcp/agent` for Den‑managed capabilities. Authentication flows through the `oauth` block if required.