# How to Set Up a Development Environment for different-ai/openwork: A Complete Guide

> Set up your development environment for different-ai/openwork easily. Clone the repo, install pnpm, run pnpm install, and start the client with pnpm dev. Get started today.

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

---

**Clone the repository, install pnpm ≥11, run `pnpm install`, then start the desktop client with `pnpm dev` — or use `pnpm dev:den` for the backend control plane.**

OpenWork is a multi-package monorepo that powers an **Electron desktop app**, a **cloud control-plane (Den)**, and a suite of plugins/MCPs. Setting up a local development environment requires understanding its **pnpm workspace structure** and the specific scripts defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json). This guide walks you through every step with commands from the actual source code.

## Prerequisites

Before starting, ensure you have the following installed:

- **Node.js ≥20** — the repository targets Node 20+
- **pnpm ≥11** — install from [pnpm.io](https://pnpm.io/installation)
- **Docker** — required for the local MySQL instance used by Den
- **Git** — for cloning and worktree operations

## Step 1: Clone and Checkout the Development Branch

The active development branch is `dev`. Always start there:

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

```

## Step 2: Install Workspace Dependencies

OpenWork uses **pnpm workspaces** to manage its monorepo structure. A single install command links all packages:

```bash
pnpm install

```

pnpm reads the implicit [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) configuration and creates a single `node_modules` directory at the repository root, linking all internal packages.

## Step 3: Start the Desktop Client

The default development target is the **Electron desktop app**. Run:

```bash
pnpm dev

```

This command, defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) at [lines 13–16](https://github.com/different-ai/openwork/blob/dev/package.json#L13-L16), performs three critical actions:

1. Sets `OPENWORK_DEV_MODE=1`
2. Forwards the Electron remote-debug port (`${OPENWORK_ELECTRON_REMOTE_DEBUG_PORT:-9823}`)
3. Invokes the `@openwork/desktop` package's `dev` script

You'll see a startup banner like:

```

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

```

The **CDP URL** (`http://127.0.0.1:9223`) is where debugging tools can attach.

## Step 4: Work-Tree Mode for Parallel Development

Need to work on two branches simultaneously? Use **work-tree mode**:

```bash
pnpm dev:worktree

```

This script, located at [package.json lines 17–20](https://github.com/different-ai/openwork/blob/dev/package.json#L17-L20), automatically:

- Sets `OPENWORK_DEV_PROFILE=auto` (derives profile name from git worktree path)
- Selects free CDP and Vite ports to avoid conflicts
- Forces `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1` to bypass macOS keychain prompts

## Step 5: Run the Backend (Den Control Plane)

OpenWork's cloud control plane lives under `ee/apps/den-*`. To start a **local Den instance**:

### 5.1 Start MySQL Container

```bash
pnpm dev:den:mysql

```

### 5.2 Apply Database Schema

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

```

This pushes the Drizzle schema defined in [[`ee/apps/den-db/src/schema/workers.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-db/src/schema/workers.ts)](https://github.com/different-ai/openwork/blob/dev/ee/apps/den-db/src/schema/workers.ts).

### 5.3 Launch API and Web UI

```bash
pnpm dev:den

```

These commands are defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) at [lines 57–69](https://github.com/different-ai/openwork/blob/dev/package.json#L57-L69). They automatically configure:

- `DATABASE_URL` pointing to the local MySQL container
- `DEN_DB_ENCRYPTION_KEY` and other defaults safe for local development

## Environment Configuration

Most scripts read configuration from environment variables. For quick setup:

```bash
cp .env.dev .env

```

The [`.env.dev`](https://github.com/different-ai/openwork/blob/dev/.env.dev) file contains sensible defaults including placeholder encryption keys and auth secrets. Edit values as needed:

| Variable | Purpose |
|----------|---------|
| `BETTER_AUTH_SECRET` | Authentication signing key |
| `DEN_DB_ENCRYPTION_KEY` | Database field encryption |
| `OPENAI_API_KEY` | LLM integrations (optional for local dev) |

## Advanced Development Scenarios

### Custom Profile with Real Keychain

```bash
OPENWORK_DEV_PROFILE=my-feature OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 pnpm dev

```

### Two Electron Windows Simultaneously

```bash
pnpm dev:electron:two

```

Useful for testing multi-window interactions or UI experiments.

## Key Source Files and Their Roles

| File Path | Purpose |
|-----------|---------|
| [[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)](https://github.com/different-ai/openwork/blob/dev/package.json) | Root workspace configuration, all dev scripts |
| [[`apps/desktop/package.json`](https://github.com/different-ai/openwork/blob/main/apps/desktop/package.json)](https://github.com/different-ai/openwork/blob/dev/apps/desktop/package.json) | Electron desktop client entry point |
| [[`apps/server/package.json`](https://github.com/different-ai/openwork/blob/main/apps/server/package.json)](https://github.com/different-ai/openwork/blob/dev/apps/server/package.json) | Server-side runtime configuration |
| [[`ee/apps/den-api/package.json`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/package.json)](https://github.com/different-ai/openwork/blob/dev/ee/apps/den-api/package.json) | Den control plane API |
| [[`ee/apps/den-db/src/schema/workers.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-db/src/schema/workers.ts)](https://github.com/different-ai/openwork/blob/dev/ee/apps/den-db/src/schema/workers.ts) | MySQL/Drizzle database schema |
| [`packages/docs/start-here/get-started.mdx`](https://github.com/different-ai/openwork/blob/dev/packages/docs/start-here/get-started.mdx) | The "Get started" page rendered in the dev UI |

## Verifying Your Setup

After running `pnpm dev`, open the URL from the startup banner (typically `http://localhost:5173`). You should see the **"Get started" page** from [`packages/docs/start-here/get-started.mdx`](https://github.com/different-ai/openwork/blob/dev/packages/docs/start-here/get-started.mdx), confirming the desktop client is fully operational.

## Summary

- **Use `pnpm dev`** for the standard desktop development workflow
- **Use `pnpm dev:worktree`** when working across multiple git branches
- **Use `pnpm dev:den`** (plus MySQL setup) for backend control plane development
- **Copy `.env.dev`** for quick environment configuration
- **All scripts are defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)** — check there first when exploring capabilities

## Frequently Asked Questions

### What is the minimum pnpm version for different-ai/openwork?

pnpm **≥11** is required. Earlier versions may not correctly resolve workspace dependencies or handle the monorepo's peer dependency structure. Install the latest from [pnpm.io/installation](https://pnpm.io/installation).

### Can I run the desktop app and Den backend simultaneously?

Yes. Run `pnpm dev` in one terminal for the desktop client, and `pnpm dev:den` (after MySQL setup) in another. They communicate through configured API endpoints and operate on separate ports by default.

### Why does work-tree mode use a mock keychain?

The mock keychain prevents **macOS system keychain permission dialogs** from blocking automated startup when using a fresh profile. Set `OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0` to use the real system keychain once you're ready to test production-like behavior.

### Where are the database encryption keys stored for local Den development?

Default encryption keys are embedded in the `pnpm dev:den:*` scripts and the [`.env.dev`](https://github.com/different-ai/openwork/blob/dev/.env.dev) file. These are **placeholder values safe only for local development** — rotate them before any production deployment.