How to Set Up the Local Development Environment for OpenWork: Worktree and Mock Keychain Guide

To set up the local development environment for OpenWork, clone the monorepo, install pnpm@11, run pnpm install, then use pnpm dev:worktree to launch an isolated instance with automatic profile management and mock keychain enabled.

OpenWork is a multi-package monorepo maintained by different-ai that combines an Electron desktop application with backend services known as the "Den" stack. Setting up the local development environment for OpenWork requires specific tooling to handle port allocation, credential isolation, and profile management across multiple git branches. This guide covers the complete setup process, including the use of git worktrees and the mock keychain configuration that prevents macOS keychain prompts from blocking the Electron main loop.

Prerequisites and Tooling

Before initializing the environment, ensure you have the required toolchain installed. OpenWork relies on pnpm as its package manager and uses specific environment variables to control runtime behavior.

• Node.js (LTS version recommended)
• Git (for worktree support)
• pnpm@11 (required by package.json which specifies pnpm@11.4.0)

Install pnpm globally with:

npm i -g pnpm@11

Clone the Repository and Install Dependencies

Retrieve the source code and resolve workspace-wide dependencies. OpenWork uses a workspace configuration defined in the root package.json to link its packages.

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

This installs all dependencies for the Electron app, the Den services, and shared libraries across the monorepo.

Understanding the Development Profile System

OpenWork uses isolated development profiles to store application state, credentials, and configuration. Each profile gets its own directory and port allocation, allowing you to run multiple instances simultaneously without conflicts.

Key environment variables controlled by the setup:

• OPENWORK_DEV_PROFILE: Identifies the profile directory (set to auto in worktree mode for path-derived stable names)
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN: Controls credential storage (defaults to 1 in worktree setups)
• OPENWORK_ELECTRON_REMOTE_DEBUG_PORT: Specifies the Chrome DevTools Protocol (CDP) port

Using Git Worktrees for Isolated Development

The pnpm dev:worktree command is the recommended approach for local development when working across multiple branches. This script, defined in package.json, automatically configures a stable profile name based on the worktree's file path.

Create a New Worktree

First, create a separate git worktree for your feature branch to isolate changes from the main codebase:

git worktree add ../openwork-feature feature-branch
cd ../openwork-feature

Launch the Worktree Environment

Run the development script which configures dynamic port allocation and the mock keychain:

pnpm dev:worktree

The script outputs a startup banner indicating the active profile and CDP endpoint:

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

This confirms that scripts/dev-local.mjs has loaded the .env.dev defaults, started any required Docker MySQL services, and spawned Turbo to run the Den services alongside the Electron process.

Configuring the Mock Keychain

The mock keychain is critical for uninterrupted development on macOS. When Chromium stores authentication cookies in a fresh profile, it triggers the macOS keychain UI modal. Because this blocks Electron's main loop, the app appears frozen without the mock keychain enabled.

Default Behavior

The pnpm dev:worktree command automatically sets:

OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1

This bypasses the system keychain, as implemented in scripts/dev-local.mjs and confirmed in test fixtures at evals/packages/hosts/src/local.ts (line 457).

Using the Real System Keychain

To test native credential storage integration, override the default:

OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 pnpm dev:worktree

Only use this configuration in isolated worktrees to avoid contaminating shared development profiles with real credentials.

Complete Setup Walkthrough

Follow these steps to configure a fully isolated OpenWork development instance:

1. Clone and install the repository dependencies
2. Create a worktree for your feature branch to ensure isolation
3. Launch with pnpm dev:worktree to enable automatic profile management and mock keychain
4. Verify the profile in the startup banner to confirm correct directory and port allocation
5. Optional: Override ports if you encounter conflicts using OPENWORK_ELECTRON_REMOTE_DEBUG_PORT and PORT environment variables

Handling Port Conflicts

If the default ports are occupied, explicitly assign new ones:

OPENWORK_DEV_PROFILE=my-custom-profile \
OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0 \
PORT=0 pnpm dev:worktree

Setting ports to 0 allows the system to assign available ports dynamically.

Verifying Your Setup

Confirm successful initialization by checking the console output for:

• The profile directory path (e.g., dev profile=openwork-feature)
• The CDP URL (e.g., cdp=http://127.0.0.1:9223)
• No macOS keychain prompts appearing (indicating mock keychain is active)

You can then connect your Chrome DevTools to the provided CDP URL for debugging the Electron renderer process.

Summary

• OpenWork is a monorepo requiring pnpm@11 and Node.js for local development
• Use pnpm dev:worktree to automatically manage isolated profiles and avoid port conflicts across git branches
• The mock keychain (OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1) prevents macOS keychain modals from blocking Electron's main thread
• Development profiles are stored in path-derived directories when using the worktree script, enabling multiple simultaneous instances
• Override OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 only when testing real credential storage in isolated environments

Frequently Asked Questions

What is the purpose of the mock keychain in OpenWork development?

The mock keychain prevents the macOS system keychain UI from displaying when Chromium attempts to store authentication cookies in a fresh development profile. Without this setting, the keychain modal blocks Electron's main loop and freezes the application. The pnpm dev:worktree command sets OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 by default to ensure automated development and CI runs proceed uninterrupted.

How do I run multiple OpenWork instances simultaneously?

Create separate git worktrees using git worktree add ../directory-name branch-name, then run pnpm dev:worktree in each directory. The script automatically generates unique profile names based on the worktree path and assigns dynamic ports, preventing conflicts between instances. Each instance operates independently with its own data directory and CDP endpoint.

Where are the development environment variables defined?

Default environment variables are stored in .env.dev at the repository root, which scripts/dev-local.mjs loads during startup. The package.json defines the dev:worktree script that sets OPENWORK_DEV_PROFILE=auto and OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 before executing the development server. You can override any variable by prepending it to the pnpm command.

Can I use the real macOS keychain for testing?

Yes, set OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 when launching the worktree environment. This forces Electron to use the native system keychain for credential storage. Only enable this in isolated worktrees to avoid credential pollution in shared profiles, and expect the macOS keychain permission prompt to appear when the app first stores authentication data.

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