How to Set Up Openwork for Local Development: A Complete Guide

To set up Openwork for local development, clone the repository, install pnpm@11, run pnpm install, and start the desktop app with pnpm dev—using environment variables like OPENWORK_DEV_PROFILE and OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN to configure isolated dev profiles and mock keychain behavior.

Openwork is a monorepo that powers a desktop Electron application, a web UI, and the Openwork Den control plane. Setting up a local development environment requires the pnpm package manager and specific configuration to manage concurrent instances and debugging ports. This guide walks through the exact steps to build and run the project locally, referencing the actual source structure and scripts from the different-ai/openwork repository.

Prerequisites and Monorepo Architecture

Openwork uses a monorepo structure where all code lives under a single repository. The project is organized into workspace packages such as @openwork/desktop and @openwork/app, which you can target individually using pnpm --filter.

Before starting, ensure you have:

• Node.js (compatible version)
• pnpm@11 (required package manager)
• Git for cloning

Install pnpm globally with:

npm i -g pnpm@11

Core Development Configuration

The development workflow revolves around environment variables that configure isolated dev profiles, Electron CDP ports, and mock keychain behavior.

Dev Profile System

The OPENWORK_DEV_PROFILE variable determines where Electron stores its user data, allowing you to run multiple concurrent instances without conflicts. The default profile is reused for a single checkout, but you can specify unique profiles for parallel development.

As documented in the README at line 86, setting OPENWORK_DEV_PROFILE=auto generates a unique profile automatically.

Electron CDP Debugging

When you run pnpm dev, Openwork automatically launches Electron with a Chrome DevTools Protocol (CDP) server on port 9823. You can override this port using OPENWORK_ELECTRON_REMOTE_DEBUG_PORT.

According to the package.json and README (line 94), this enables remote debugging and automation tooling to connect to the running Electron instance.

Mock Keychain Configuration

For fast iteration during development, Openwork mocks the Electron keychain by default when using worktree mode. Set OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 to use the mock implementation, or set it to 0 to use the real OS keychain. This is particularly useful when running multiple instances simultaneously.

Step-by-Step Setup Instructions

1. Clone the Repository and Install Dependencies

Retrieve the full codebase and install workspace dependencies:

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

2. Run the Default Development Profile

Start the desktop application with the standard development configuration:

pnpm dev

This command, defined in package.json at line 5, launches the @openwork/desktop package with a shared dev profile and CDP server on port 9823. The console prints a banner like [openwork] dev profile=… cdp=http://127.0.0.1:9823 for connecting debugging tools.

3. Worktree Mode for Multiple Instances

To run multiple concurrent instances—useful for testing parallel feature branches—use worktree mode:

pnpm dev:worktree

This script sets OPENWORK_DEV_PROFILE=auto, enables the mock keychain (OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1), and automatically assigns free ports. Alternatively, manually specify a profile:

OPENWORK_DEV_PROFILE=feature-xyz pnpm dev

4. Start the Optional Den Backend Stack

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

# Start MySQL container

pnpm dev:den:mysql

# Push the Prisma schema

pnpm dev:den:db-push

# Seed with demo data

pnpm dev:den:seed-demo

These scripts are defined in package.json (lines 53 and related entries) and orchestrate the MySQL database, Den API, and inference services defined in packaging/docker/docker-compose.web-local.yml.

Key Development Files and Scripts

Understanding these core files helps navigate the local development setup:

• package.json – Defines all pnpm scripts including dev, dev:worktree, and the dev:den:* family of commands for backend services.
• scripts/dev-local.mjs – Entry point for the dev:den workflow that boots Den services and wires environment variables.
• .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 MySQL and Den containers used in the full stack setup.

Summary

• Clone and install using git clone and pnpm install after installing pnpm@11 globally.
• Run basic dev with pnpm dev to start the Electron desktop app with CDP on port 9823.
• Use worktree mode (pnpm dev:worktree or OPENWORK_DEV_PROFILE=auto) for isolated instances with mock keychains.
• Configure CDP via OPENWORK_ELECTRON_REMOTE_DEBUG_PORT to change the default debugging port from 9823.
• Start Den backend using the dev:den:mysql, dev:den:db-push, and dev:den:seed-demo scripts for full-stack development.
• Reference scripts/dev-local.mjs and package.json for the implementation details of the development workflow.

Frequently Asked Questions

What is the default CDP port for Electron debugging?

The default CDP (Chrome DevTools Protocol) port is 9823. When you run pnpm dev, Openwork automatically launches Electron with the debugger listening on this port. You can override this by setting the OPENWORK_ELECTRON_REMOTE_DEBUG_PORT environment variable to a different port number or 0 to auto-select a free port.

How do I run multiple instances of Openwork simultaneously?

Use the worktree mode by running pnpm dev:worktree, which automatically sets OPENWORK_DEV_PROFILE=auto and enables the mock keychain. Alternatively, manually specify unique profiles for each instance: OPENWORK_DEV_PROFILE=instance-1 pnpm dev in one terminal and OPENWORK_DEV_PROFILE=instance-2 pnpm dev in another. Each profile maintains separate user data directories.

What is the Den stack and when do I need it?

The Den stack is the self-hosted backend component of Openwork consisting of MySQL, the Den API, and inference services. You need it only when developing backend features or testing full end-to-end workflows. Start it with pnpm dev:den:mysql and related scripts defined in package.json. For frontend-only development of the desktop app, you can skip this step.

How do I disable the mock keychain and use the real OS keychain?

Set OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 when starting the application. By default, worktree mode sets this to 1 for faster iteration and to avoid conflicts between multiple instances. When set to 0, Electron will use the native OS keychain (macOS Keychain, Windows Credential Manager, etc.) to store sensitive data.

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