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

> Build OpenWork from source code with our step-by-step developer guide. Clone the repo, install pnpm dependencies, and run pnpm dev to launch the app.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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:

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

```

Install workspace dependencies once at the root:

```bash
pnpm install

```

This command reads the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) and installs each workspace package into a shared `node_modules` folder. The pnpm workspace is defined by [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/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:

```bash
pnpm dev

```

This starts the **Electron** main process defined in [`apps/electron/main.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/electron/main.ts) handles process spawning and CDP wiring.

### Work-Tree Aware Development

If you maintain multiple checkouts, use:

```bash
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:

```bash
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`](https://github.com/different-ai/openwork/blob/main/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:

```bash
pnpm build

```

This invokes **electron-builder** configured in [`apps/electron/package.json`](https://github.com/different-ai/openwork/blob/main/apps/electron/package.json) and outputs installers to `dist/`. Verify the exact build script in the `scripts` field of [`apps/electron/package.json`](https://github.com/different-ai/openwork/blob/main/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):

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/apps/electron/main.ts) supports keychain mocking via `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN` for automated testing.

## Complete Build Workflow

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/electron/package.json). For Den API problems, review [`ee/apps/den-api/package.json`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/package.json). The unified lockfile at [`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml) ensures reproducible installs when dependencies change.