# How to Build different-ai/openwork From Source: Complete Development Guide

> Learn to build different-ai/openwork from source with this complete development guide. Install dependencies and run the app to start contributing.

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

---

**To build OpenWork from source, clone the `dev` branch, install dependencies with `pnpm install`, and run `pnpm dev` to launch the Electron desktop client and Den server in development mode.**

OpenWork is a multi-platform desktop application for sharing AI workflows. This guide walks through the complete build process—from cloning the repository to producing production artifacts—based on the actual source code structure in `different-ai/openwork`.

## Prerequisites

Before building OpenWork, ensure you have the following tools installed:

| Requirement | Purpose | Verification Command |
|-------------|---------|----------------------|
| **Git** | Clone the repository | `git --version` |
| **Node ≥ 20** | Modern ECMAScript and TypeScript 5.x features | `node -v` |
| **pnpm ≥ 8** | Workspace-aware monorepo management | `pnpm -v` |
| **Docker** (optional) | Den server services (MySQL, Redis) | `docker --version` |
| **Python ≥ 3.9** (optional) | Compile native dependencies like `better-sqlite3` | `python3 --version` |

## Clone the Repository

OpenWork actively develops on the `dev` branch. The source code resides in the `dev` folder of the repository.

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

```

The root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) at `https://github.com/different-ai/openwork/blob/dev/package.json` defines the workspace structure.

## Install Workspace Dependencies

OpenWork uses a **pnpm workspace** configured in [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml). This monorepo includes packages under `apps/*`, `packages/*`, `ee/apps/*`, and `ee/packages/*`.

```bash
pnpm install

```

This command hoists shared dependencies to a single root `node_modules` and links local packages per the workspace configuration at `https://github.com/different-ai/openwork/blob/dev/pnpm-workspace.yaml`.

## Run the Development Environment

### Basic Development Mode

The standard `pnpm dev` command launches the full stack:

```bash
pnpm dev

```

This sets `OPENWORK_DEV_MODE=1` and starts:
- The **Electron desktop client** (`@openwork/desktop`)
- The **Den server** (API + Web UI)

You will see console output including:

```

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

```

The **profile directory** and **Chrome DevTools Protocol (CDP) URL** are displayed for tooling integration.

### Worktree-Friendly Development

For developers using multiple Git worktrees:

```bash
pnpm dev:worktree

```

This command:
- Sets `OPENWORK_DEV_PROFILE=auto` to isolate profiles per worktree
- Defaults `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1` to bypass macOS keychain prompts

The keychain bypass prevents blocking dialogs during fresh profile initialization, as implemented in `scripts/dev-two-electron-demo.mjs` at `https://github.com/different-ai/openwork/blob/dev/scripts/dev-two-electron-demo.mjs`.

### Two-Electron Demo Mode

Test multi-user scenarios with two isolated Electron instances:

```bash
pnpm dev:electron:two

```

Available flags (run `pnpm dev:electron:two --help` for complete list):

| Flag | Purpose |
|------|---------|
| `--built` | Use pre-built renderer (skip Vite) |
| `--packaged` | Launch packaged `.app` bundles (macOS only) |
| `--reset` | Clear demo data and stop lingering processes |
| `--admin-port` / `--consumer-port` | Vite dev server ports (default: 5273 / 5274) |
| `--admin-cdp` / `--consumer-cdp` | CDP ports (default: 9923 / 9924) |

The script creates temporary bootstrap files ([`admin-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/admin-bootstrap.json), [`consumer-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/consumer-bootstrap.json)) in `/tmp/openwork-two-electron-demo` containing Den URLs and branding configuration.

## Build Production Artifacts

### Desktop App

```bash
pnpm --filter @openwork/desktop build

```

Output targets `apps/desktop/dist`. The repository includes `scripts/build.mjs` for Electron Builder packaging.

### Den Web UI

```bash
pnpm --filter @openwork-ee/den-web build

```

Static assets compile to `apps/den-web/.next` per the Next.js configuration.

### UI Playground

```bash
pnpm --filter @openwork/app build

```

Produces the Vite bundle used by the desktop renderer.

### Full Release Pipeline

```bash
pnpm release:prepare   # Changelogs, version bumps, checks

pnpm release:ship      # Asset publication (requires CI credentials)

```

Both commands require a clean Git state and will abort on uncommitted changes.

## Run Tests

OpenWork uses **@openwork/testkit** with specs in `evals/specs`:

```bash
pnpm test:e2e           # Desktop app UI tests

pnpm evals:test         # Spec runner automation mode

pnpm run test:health    # Application health checks

```

Filter to specific packages with `pnpm --filter <package>`.

## Key Source Files

| Path | Purpose |
|------|---------|
| [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) (root) | Workspace definition, shared scripts |
| [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) | Workspace packages and version catalogs |
| [`apps/desktop/package.json`](https://github.com/different-ai/openwork/blob/main/apps/desktop/package.json) | Desktop client entry point |
| `apps/desktop/scripts` | Build helpers, side-car preparation |
| `scripts/dev-two-electron-demo.mjs` | Two-Electron orchestration script |
| [`apps/den-web/package.json`](https://github.com/different-ai/openwork/blob/main/apps/den-web/package.json) | Next.js web UI |
| [`apps/den-api/package.json`](https://github.com/different-ai/openwork/blob/main/apps/den-api/package.json) | Fastify/Hono backend |
| `evals/runner/run.mjs` | Test-kit spec runner CLI |

## Summary

- **Clone** the `dev` branch from `different-ai/openwork`
- **Install** with `pnpm install` for workspace-aware dependency management
- **Develop** using `pnpm dev` (standard) or `pnpm dev:worktree` (multi-checkout)
- **Test** multi-user scenarios with `pnpm dev:electron:two`
- **Build** production artifacts with filtered pnpm commands
- **Release** via the `release:prepare` and `release:ship` pipeline

## Frequently Asked Questions

### Why does `pnpm dev:worktree` use a mock keychain?

The `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1` setting prevents macOS keychain prompts from blocking the Electron main loop when initializing fresh profiles. Disable by setting the environment variable to `0` to test real credential storage.

### Can Den services run without Docker?

Yes. Configure `DATABASE_URL` to point to any MySQL instance. The default `mysql://root:password@127.0.0.1:3306/openwork_den` works with manually managed MySQL servers.

### What is `OPENWORK_ELECTRON_REMOTE_DEBUG_PORT`?

This environment variable opens a Chrome DevTools Protocol listener for debugging or automation. Defaults are `9823` for single instances, `9923/9924` for the two-Electron demo pair.

### How do I troubleshoot `better-sqlite3` build failures?

Ensure Python ≥ 3.9 is installed and accessible. Native module compilation requires a working Python environment and build tools appropriate for your platform.