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

> Set up Openwork for local development: Clone the repo, install pnpm, and run commands to start the app. Configure dev profiles and mock keychain with environment variables for isolated testing.

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

---

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

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

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

```bash
pnpm dev

```

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

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

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

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packaging/docker/docker-compose.web-local.yml).

## Key Development Files and Scripts

Understanding these core files helps navigate the local development setup:

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