# How to Set Up the Local Development Environment for OpenWork: Worktree and Mock Keychain Guide > Set up your OpenWork local development environment with worktree and mock keychain. Clone, install dependencies, and launch an isolated instance for seamless development. - Repository: [Different AI/openwork](https://github.com/different-ai/openwork) - Tags: how-to-guide - Published: 2026-08-04 --- **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`](https://github.com/different-ai/openwork/blob/main/package.json) which specifies `pnpm@11.4.0`) Install pnpm globally with: ```bash 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`](https://github.com/different-ai/openwork/blob/main/package.json) to link its packages. ```bash 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`](https://github.com/different-ai/openwork/blob/main/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: ```bash 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: ```bash pnpm dev:worktree ``` The script outputs a startup banner indicating the active profile and CDP endpoint: ```bash [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: ```bash 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`](https://github.com/different-ai/openwork/blob/main/evals/packages/hosts/src/local.ts) (line 457). ### Using the Real System Keychain To test native credential storage integration, override the default: ```bash 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: ```bash 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`](https://github.com/different-ai/openwork/blob/main/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.