How to Build OpenWork from Source: Step-by-Step Guide for Developers

Build OpenWork from source by cloning the repository, installing pnpm dependencies with pnpm install, and running pnpm dev to launch the Electron desktop application.

OpenWork is an open-source, cross-platform desktop application built with Electron, React, Vite, and pnpm. This guide walks you through building OpenWork from source, covering the desktop UI, headless web mode, and the full Den micro-services stack. The repository different-ai/openwork uses a monorepo structure with pnpm workspaces to manage dependencies across multiple packages.

Prerequisites to Build OpenWork from Source

Before you begin, ensure your environment meets these requirements:

• Node.js ≥ 18 – required by pnpm and the Electron runtime
• pnpm – install globally with npm i -g pnpm
• Git – to clone the repository
• Docker & MySQL (optional) – only needed for the full Den stack and integration tests

Clone the Repository and Install Dependencies

Start by cloning the OpenWork repository and checking out the dev branch:

git clone https://github.com/different-ai/openwork.git
cd openwork
git checkout dev

Install workspace dependencies once at the root:

pnpm install

This command reads the root package.json and installs each workspace package into a shared node_modules folder. The pnpm workspace is defined by pnpm-workspace.yaml at the repository root, which groups packages under apps/, packages/, and ee/ into a unified dependency graph with a single lockfile.

Run OpenWork in Development Mode

Standard Desktop Development (Electron + Vite)

Launch the desktop application with:

pnpm dev

This starts the Electron main process defined in apps/electron/main.ts, boots the Vite dev server, and prints a diagnostic banner:

[openwork] dev profile=default cdp=http://127.0.0.1:9223

The banner shows your profile directory and the Chrome DevTools Protocol (CDP) endpoint for debugging. The Electron entry point at apps/electron/main.ts handles process spawning and CDP wiring.

Work-Tree Aware Development

If you maintain multiple checkouts, use:

pnpm dev:worktree

This automatically generates profile names from your current git work-tree, isolates keychain access, and prevents profile-lock collisions.

Headless Web Mode (No Electron)

For agent-driven automation without a desktop window:

pnpm dev:headless-web

This starts:

• A Vite-powered web UI
• A local openwork-server instance

The command writes connection details to tmp/dev-headless-web.json and detaches processes from your terminal. This mode is essential for bots that cannot drive Electron windows.

Build a Production Bundle

Create distributable installers for CI or manual distribution:

pnpm build

This invokes electron-builder configured in apps/electron/package.json and outputs installers to dist/. Verify the exact build script in the scripts field of apps/electron/package.json if your version differs.

Run the Full Den Stack Locally

To develop against the complete backend (teams, model provisioning, policies, marketplaces):

# Start MySQL container

pnpm dev:den:mysql

# Apply database schema and seed demo data

pnpm dev:den:db-push
pnpm dev:den:seed-demo

# Launch API, Web UI, and worker proxy

pnpm dev:den

The Den services listen on:

• Port 8788 – Den API
• Port 8778 – Den server

These are automatically proxied for the desktop UI. The micro-services architecture resides under ee/apps/den-api and ee/apps/den-web, with route definitions in ee/apps/den-api/src/routes/*.

Architecture Overview

Understanding the three layers helps troubleshoot build issues:

Layer	Location	Purpose
Desktop app	apps/electron/, packages/	Electron host with React/Vite UI
MCP gateway	ee/apps/den-api/src/routes/*	Remote capability server for agents
Den control plane	ee/apps/den-api, ee/apps/den-web	Team management, models, policies

All layers share the pnpm workspace for consistent dependency management. The Electron main process in apps/electron/main.ts supports keychain mocking via OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN for automated testing.

Complete Build Workflow

# 1. Clone & install

git clone https://github.com/different-ai/openwork.git
cd openwork && git checkout dev
pnpm install

# 2. Desktop development

pnpm dev

# 3. Headless automation mode

pnpm dev:headless-web --detach

# 4. Production build

pnpm build

# 5. Full stack with Den backend

pnpm dev:den:mysql
pnpm dev:den:db-push
pnpm dev:den:seed-demo
pnpm dev:den

Summary

• Single install: pnpm install at the root satisfies all workspace packages
• Three dev modes: pnpm dev (desktop), pnpm dev:worktree (isolated), pnpm dev:headless-web (automation)
• Build command: pnpm build creates distributable Electron installers
• Den stack: Optional backend requires Docker/MySQL and runs via pnpm dev:den shortcuts
• Key source files: Electron entry at apps/electron/main.ts, routes at ee/apps/den-api/src/routes/*

Frequently Asked Questions

What Node.js version is required to build OpenWork?

Node.js 18 or higher is required. This version is necessary for pnpm compatibility and the Electron runtime. Older versions will fail during dependency resolution or Electron launch.

Can I build OpenWork without installing Docker?

Yes, for desktop development only. Run pnpm dev or pnpm dev:headless-web without any Docker setup. Docker is only required for the Den backend stack (pnpm dev:den commands) and integration testing.

Where is the Electron main process code located?

The main process lives in apps/electron/main.ts. This file bootstraps the Vite dev server, creates the browser window, and exposes the CDP debugging endpoint. The preload script at apps/electron/preload.ts handles secure IPC between main and renderer processes.

How do I debug build failures in the pnpm workspace?

Check the root package.json scripts and individual package manifests. Since OpenWork uses pnpm workspaces, most commands delegate to specific packages. For Electron issues, inspect apps/electron/package.json. For Den API problems, review ee/apps/den-api/package.json. The unified lockfile at pnpm-lock.yaml ensures reproducible installs when dependencies change.

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