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

> Set up OpenWork for local development with this monorepo guide. Clone the repo, install pnpm, and run pnpm dev to launch the Electron app with CDP support.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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:

```bash
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:

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

```

2. Install dependencies across all workspace packages:

```bash
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`](https://github.com/different-ai/openwork/blob/main/package.json) that delegate to specific workspaces.

- **`@openwork/desktop`** – The Electron application
- **`@openwork/app`** – The web UI components

The root [`package.json`](https://github.com/different-ai/openwork/blob/main/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:

```bash
pnpm dev

```

According to the [`package.json`](https://github.com/different-ai/openwork/blob/main/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:

```bash
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:

```bash
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`](https://github.com/different-ai/openwork/blob/main/package.json) and orchestrated via `scripts/dev-local.mjs`.

1. Start the MySQL container:

```bash
pnpm dev:den:mysql

```

2. Push the Prisma schema to the database:

```bash
pnpm dev:den:db-push

```

3. Seed the database with demo organization data:

```bash
pnpm dev:den:seed-demo

```

The Docker configuration resides in [`packaging/docker/docker-compose.web-local.yml`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/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.