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

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.

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

The root 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. This monorepo includes packages under apps/*, packages/*, ee/apps/*, and ee/packages/*.

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:

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:

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:

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, consumer-bootstrap.json) in /tmp/openwork-two-electron-demo containing Den URLs and branding configuration.

Build Production Artifacts

Desktop App

pnpm --filter @openwork/desktop build

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

Den Web UI

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

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

UI Playground

pnpm --filter @openwork/app build

Produces the Vite bundle used by the desktop renderer.

Full Release Pipeline

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:

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 (root)	Workspace definition, shared scripts
pnpm-workspace.yaml	Workspace packages and version catalogs
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	Next.js web UI
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.

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