How to Set Up OpenWork for Local Development: Complete Monorepo Guide

To set up OpenWork for local development, clone the repository, install pnpm@11, run pnpm install, and execute pnpm dev to launch the Electron desktop app with Chrome DevTools Protocol (CDP) support on port 9823.

The different-ai/openwork repository is a monorepo containing the desktop Electron application, web UI, and Den control plane. The development workflow relies on pnpm workspace filtering and environment variables that manage isolated user data profiles, debugging ports, and optional backend services.

Prerequisites

Before starting, ensure your system meets the baseline requirements. OpenWork strictly uses pnpm as its package manager, and the repository requires Node.js support via pnpm@11.

• Git for cloning the repository
• Node.js (version compatible with pnpm@11)
• pnpm@11 installed globally:

npm i -g pnpm@11

Clone the Repository and Install Dependencies

Retrieve the full codebase and resolve all workspace packages using pnpm's monorepo-aware installer.

1. Clone the repository:

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

2. Install dependencies across all workspace packages:

pnpm install

This command resolves dependencies for all packages in the monorepo, including @openwork/desktop and @openwork/app.

Understanding the Monorepo Structure

OpenWork organizes code as a pnpm workspace where individual applications live as separate packages. You target specific packages using the --filter flag or run root-level scripts defined in package.json that delegate to specific workspaces.

• @openwork/desktop – The Electron application
• @openwork/app – The web UI components

The root package.json defines convenience scripts that wrap pnpm --filter commands, allowing you to start services without memorizing workspace syntax.

Running the Development Server

The primary development command launches the desktop application with automatic CDP server initialization for debugging and automation.

Default Dev Profile

Execute the standard development command to start the Electron app with a shared user data directory:

pnpm dev

According to the package.json dev script, this command:

• Launches the @openwork/desktop package
• Initializes the CDP server on port 9823 (default)
• Creates or reuses the default development profile for Electron user data storage

The console outputs a banner displaying the active profile and CDP endpoint: [openwork] dev profile=… cdp=http://127.0.0.1:9823.

Worktree Mode for Parallel Development

When developing multiple features simultaneously, worktree mode isolates each instance with unique user data directories and randomized ports. This prevents conflicts between running Electron instances.

Run the worktree-specific command:

pnpm dev:worktree

This script automatically sets:

• OPENWORK_DEV_PROFILE=auto (generates unique profile IDs)
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 (bypasses OS keychain)
• OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0 and PORT=0 (auto-assigns free ports)

For manual control over concurrent instances, specify explicit environment variables:

OPENWORK_DEV_PROFILE=feature-xyz pnpm dev

Configuring Environment Variables

OpenWork behavior is controlled through specific environment variables that configure the runtime environment without modifying source code.

• OPENWORK_DEV_PROFILE – Determines Electron's user data storage location. Set to auto for randomized isolation, or use a specific string (e.g., feature-xyz) for repeatable sessions across restarts.
• OPENWORK_ELECTRON_REMOTE_DEBUG_PORT – Overrides the default CDP port (9823). Set to 0 to auto-assign a free port.
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN – Controls authentication storage. Set to 1 for a mocked in-memory keychain (fastest for development), or 0 to use the native OS keychain.

These variables are documented in the repository's README and processed by the Electron main process initialization logic.

Setting Up the Den Backend (Optional)

For full end-to-end development including the self-hosted backend, OpenWork provides Docker-based scripts to spin up MySQL and the Den API. These are defined in package.json and orchestrated via scripts/dev-local.mjs.

1. Start the MySQL container:

pnpm dev:den:mysql

2. Push the Prisma schema to the database:

pnpm dev:den:db-push

3. Seed the database with demo organization data:

pnpm dev:den:seed-demo

The Docker configuration resides in packaging/docker/docker-compose.web-local.yml, defining the MySQL and Den service containers. The scripts/dev-local.mjs entry point handles environment variable wiring and service orchestration.

Verifying Your Installation

Confirm successful setup by checking the running services:

• Desktop UI: Open the Electron window or navigate to http://localhost:5173
• Den API: Access the backend at http://localhost:3005 (if running the full stack)
• CDP Endpoint: Connect Chrome DevTools or automation agents to http://127.0.0.1:9823 (or the auto-assigned port displayed in the console banner)

The CDP functionality is documented in .opencode/skills/browser-automation/SKILL.md, which details how the pnpm dev command enables browser automation capabilities for testing.

Summary

Setting up OpenWork for local development requires understanding its monorepo architecture and environment configuration system:

• Install pnpm@11 globally before proceeding
• Use pnpm dev to start the default Electron profile on port 9823
• Leverage worktree mode (pnpm dev:worktree) for isolated parallel development with OPENWORK_DEV_PROFILE=auto
• Enable mock keychain (OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1) to bypass OS authentication during rapid iteration
• Run Den backend services via pnpm dev:den:* scripts when testing full-stack integration
• Reference package.json for script definitions and scripts/dev-local.mjs for service orchestration logic

Frequently Asked Questions

What package manager does OpenWork require?

OpenWork strictly requires pnpm@11. The repository uses pnpm workspaces to manage the monorepo structure, and scripts are specifically designed around pnpm's --filter functionality. Using npm or yarn will result in dependency resolution failures.

How do I run multiple instances of OpenWork simultaneously?

Set the OPENWORK_DEV_PROFILE environment variable to unique values for each instance, or use pnpm dev:worktree which automatically sets OPENWORK_DEV_PROFILE=auto and assigns random ports. This prevents Electron user data directory collisions and port conflicts between instances.

Why should I use the mock keychain during development?

Setting OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 replaces the native OS keychain with an in-memory mock, eliminating permission prompts and authentication delays. This configuration is enabled by default in worktree mode and significantly accelerates the development feedback loop when testing features requiring credential storage.

Do I need Docker for local development?

Docker is only required if you are developing features that interact with the Den backend (self-hosted control plane). For pure desktop application development, you can run pnpm dev without any Docker containers. When needed, the pnpm dev:den:* scripts handle MySQL and API container orchestration automatically.

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