How to Set Up a Local Development Environment for OpenWork: Complete Setup Guide

You can set up a local OpenWork development environment by cloning the different-ai/openwork repository, installing pnpm@11, running pnpm install, and executing pnpm dev to launch the Electron desktop app with Chrome DevTools Protocol (CDP) enabled on port 9823.

OpenWork is an open-source monorepo that powers a desktop Electron application, a web-based user interface, and the OpenWork Den control plane. The development workflow relies on the pnpm package manager and environment variables that configure isolated dev profiles, debugging ports, and keychain behavior.

Prerequisites and Installation

Before you begin, ensure you have Node.js installed locally. You also need pnpm version 11, which OpenWork uses to manage its workspace packages.

Install pnpm globally:

npm i -g pnpm@11

Clone the repository and install dependencies:

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

This resolves all workspace packages defined in the monorepo structure, including @openwork/desktop and @openwork/app.

Understanding the Monorepo Structure

OpenWork is organized as a monorepo where all code lives under a single repository. The project uses pnpm --filter to target specific packages when running commands.

Key packages include:

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

The root package.json defines scripts that proxy commands to these filtered workspaces, allowing you to run the entire stack or individual components.

Basic Development Workflow

Configure Environment Variables

OpenWork uses several environment variables to control development behavior. These variables isolate your development instance and configure debugging capabilities:

• OPENWORK_DEV_PROFILE – Determines where Electron stores user data, enabling multiple concurrent instances. The default profile is reused for a single checkout.
• OPENWORK_ELECTRON_REMOTE_DEBUG_PORT – Sets the Chrome DevTools Protocol port. Defaults to 9823 if not specified.
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN – Set to 1 to use a mock keychain for fast iteration, or 0 to use the real OS keychain.

Launch the Development Server

Run the default development profile:

pnpm dev

This command, defined in package.json at line 5, launches the Electron desktop application with CDP enabled. The console displays a banner similar to [openwork] dev profile=… cdp=http://127.0.0.1:9823.

Verify the setup by opening:

• The Electron window directly, or
• http://localhost:5173 to view the desktop UI in a browser
• http://localhost:3005 for the Den API (when running the backend stack)

Advanced Development Workflows

Worktree Mode for Parallel Development

When working on multiple feature branches simultaneously, use worktree mode to launch isolated instances with automatic port allocation and mock keychain enabled:

pnpm dev:worktree

This command sets OPENWORK_DEV_PROFILE=auto, enables OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1, and assigns free ports automatically. As documented in README.md at line 91, this prevents conflicts between development instances.

Alternatively, manually specify a unique profile name:

OPENWORK_DEV_PROFILE=feature-branch-name pnpm dev

Running the Den Backend Stack

For full end-to-end development including the self-hosted backend, start the Docker-based Den services:

pnpm dev:den:mysql      # Spins up MySQL container

pnpm dev:den:db-push    # Pushes Prisma schema

pnpm dev:den:seed-demo  # Seeds demo organization data

These commands, defined in package.json (lines 53 and related entries), execute scripts/dev-local.mjs to bootstrap the environment. The configuration references packaging/docker/docker-compose.web-local.yml to define MySQL and Den API containers.

Key Configuration Files

Understanding these source files helps you customize your development environment:

• README.md – Contains the Local development section (line 86) documenting dev profiles and the dev:worktree command (line 91)
• package.json – Defines all pnpm scripts including dev, dev:worktree, and dev:den:mysql
• scripts/dev-local.mjs – Entry point for Den service orchestration
• .opencode/skills/browser-automation/SKILL.md – Documents how pnpm dev enables Electron CDP for automation testing
• packaging/docker/docker-compose.web-local.yml – Docker Compose configuration for the local MySQL and Den API services

Summary

• OpenWork requires pnpm@11 as its package manager and uses a monorepo structure filtered with pnpm --filter
• Run pnpm dev to start the Electron desktop app with CDP debugging on port 9823
• Use OPENWORK_DEV_PROFILE to isolate user data directories when running multiple instances
• Enable OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 for faster iteration without OS keychain prompts
• Launch pnpm dev:worktree for automatic profile isolation and concurrent development
• Start the Den backend via pnpm dev:den:mysql and related commands when you need the full stack running locally

Frequently Asked Questions

What package manager does OpenWork require?

OpenWork requires pnpm version 11. The project uses pnpm workspaces to manage the monorepo structure, and scripts are specifically designed around pnpm's filtering capabilities. You cannot use npm or yarn to install dependencies successfully.

How do I run multiple instances of the OpenWork desktop app simultaneously?

Set the OPENWORK_DEV_PROFILE environment variable to a unique name for each instance, or use pnpm dev:worktree which automatically sets OPENWORK_DEV_PROFILE=auto. This ensures each instance stores user data in separate directories. You can also override OPENWORK_ELECTRON_REMOTE_DEBUG_PORT and PORT to avoid conflicts.

Do I need Docker to develop the OpenWork desktop application?

No, Docker is optional for desktop-only development. However, if you want to run the OpenWork Den backend services locally—including MySQL and the API layer—you must have Docker installed to execute the pnpm dev:den:mysql and related scripts defined in package.json.

How do I connect to the Electron CDP for debugging?

When you run pnpm dev, OpenWork automatically launches Electron with the Chrome DevTools Protocol enabled on port 9823 (or the port specified by OPENWORK_ELECTRON_REMOTE_DEBUG_PORT). Connect your debugger to http://127.0.0.1:9823 or use the CDP URL printed in the console banner. This is implemented according to the browser automation documentation in .opencode/skills/browser-automation/SKILL.md.

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