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

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. 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
• 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:

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:

pnpm install

pnpm reads the implicit 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:

pnpm dev

This command, defined in the root package.json at lines 13–16, 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:

pnpm dev:worktree

This script, located at package.json lines 17–20, 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

pnpm dev:den:mysql

5.2 Apply Database Schema

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/dev/ee/apps/den-db/src/schema/workers.ts).

5.3 Launch API and Web UI

pnpm dev:den

These commands are defined in the root package.json at lines 57–69. 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:

cp .env.dev .env

The .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

OPENWORK_DEV_PROFILE=my-feature OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 pnpm dev

Two Electron Windows Simultaneously

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/dev/package.json)	Root workspace configuration, all dev scripts
[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/dev/apps/server/package.json)	Server-side runtime configuration
[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/dev/ee/apps/den-db/src/schema/workers.ts)	MySQL/Drizzle database schema
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, 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 — 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.

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 file. These are placeholder values safe only for local development — rotate them before any production deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}