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

> Set up your local OpenWork development environment easily. Clone the repo, install pnpm, and run pnpm dev to launch the Electron app with CDP enabled on port 9823.

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

---

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

```bash
npm i -g pnpm@11

```

Clone the repository and install dependencies:

```bash
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`](https://github.com/different-ai/openwork/blob/main/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:

```bash
pnpm dev

```

This command, defined in [`package.json`](https://github.com/different-ai/openwork/blob/main/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:

```bash
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`](https://github.com/different-ai/openwork/blob/main/README.md) at line 91, this prevents conflicts between development instances.

Alternatively, manually specify a unique profile name:

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

```bash
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/README.md)** – Contains the Local development section (line 86) documenting dev profiles and the `dev:worktree` command (line 91)
- **[`package.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.opencode/skills/browser-automation/SKILL.md)** – Documents how `pnpm dev` enables Electron CDP for automation testing
- **[`packaging/docker/docker-compose.web-local.yml`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.opencode/skills/browser-automation/SKILL.md).