# How to Install different-ai/openwork Locally: A Complete Setup Guide

> Install different-ai/openwork locally with this complete setup guide. Clone the repo, install pnpm, and run simple commands to start the desktop client or backend.

- 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 the backend with `pnpm dev:den`.**

OpenWork is a multi-component workspace platform that combines an **Electron desktop client**, a **backend server ("Den")**, and supporting libraries in a unified monorepo. Installing different-ai/openwork locally requires setting up the Node/pnpm toolchain, pulling dependencies, and launching your desired components. This guide walks through the exact steps used by maintainers, referencing the actual source files and scripts from the repository.

## Prerequisites for OpenWork Local Installation

Before installing openwork locally, ensure these tools are available on your system:

- **Node.js LTS** – Required for all build processes
- **pnpm@11** – The monorepo's pinned package manager (version 11.4.0)
- **Rust toolchain** – Needed for Tauri/Electron native builds
- **OpenCode CLI** – Used for code generation workflows

The prerequisite checklist appears in [`dev/translated_readmes/README_ZH.md`](https://github.com/different-ai/openwork/blob/main/dev/translated_readmes/README_ZH.md) 【source: translated README (zh) → "Tauri CLI: `cargo install tauri-cli`"】, while Node.js and pnpm requirements are documented in the main [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) 【source: README → "Node.js + `pnpm`"】.

## Step 1: Clone the Repository and Checkout the Dev Branch

OpenWork follows a `dev` branch workflow. Clone and switch branches:

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

```

## Step 2: Install pnpm (Version 11)

The repository pins pnpm at version 11.4.0. Install globally to match:

```bash
npm i -g pnpm@11

```

This ensures lockfile compatibility across the monorepo's `packages/` and `apps/` directories.

## Step 3: Install All Workspace Dependencies

The monorepo uses a single pnpm lockfile. One command fetches every dependency:

```bash
pnpm install

```

This resolves packages for the desktop client, Den server, UI demos, and shared libraries defined under `packages/@openwork/*` 【source: README → "pnpm install"】.

## Step 4: Launch the Desktop Client

The desktop client is an Electron application defined in `packages/@openwork/desktop/`. Start it in development mode:

```bash

# Standard development mode

pnpm dev

```

### Worktree-Isolated Development

If you use multiple git worktrees, prevent profile conflicts with:

```bash
pnpm dev:worktree

```

This sets `OPENWORK_DEV_PROFILE=auto`, creating an isolated directory per worktree with separate Chrome/Electron data stores. The startup banner prints the CDP debugging endpoint:

```

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

```

These scripts are defined in [`dev/package.json`](https://github.com/different-ai/openwork/blob/main/dev/package.json) 【source: package.json → `"dev"` & `"dev:worktree"`】.

## Step 5: Launch the Den Backend Server

The **Den** server provides the web control plane and workspace management. It requires a MySQL database.

### Start the Database and Apply Migrations

```bash

# Launch MySQL container

pnpm dev:den:mysql

# Push schema migrations

pnpm dev:den:db-push

```

### Start the Server and UI

```bash
pnpm dev:den

```

This brings up the HTTP server ([`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts)) and its associated UI. Server-side workspace logic resides in [`apps/server/src/workspaces.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/workspaces.ts), which implements CRUD operations for the core data model 【source: package.json → `dev:den*`】.

## Step 6: Run the UI-Only Demo (Optional)

For rapid UI iteration without the full Electron stack:

```bash
pnpm dev:ui

```

This launches the minimal React application from [`apps/ui-demo/src/main.tsx`](https://github.com/different-ai/openwork/blob/main/apps/ui-demo/src/main.tsx).

## Understanding the OpenWork Architecture

Knowing the directory structure helps when installing openwork locally for development:

| Directory | Purpose | Key Files |
|-----------|---------|-----------|
| `packages/@openwork/` | Shared libraries (desktop, app core) | `packages/@openwork/desktop/src/main.ts` |
| `apps/server/` | Den backend API | [`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts), [`apps/server/src/workspaces.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/workspaces.ts) |
| `apps/ui-demo/` | Standalone React UI | [`apps/ui-demo/src/main.tsx`](https://github.com/different-ai/openwork/blob/main/apps/ui-demo/src/main.tsx) |
| `dev/scripts/` | Build and release helpers | Migration and diagnostic tools |

The [`dev/package.json`](https://github.com/different-ai/openwork/blob/main/dev/package.json) serves as the command central for all local development scripts 【source: dev/package.json】.

## Complete Installation Command Reference

```bash

# Full setup from scratch

git clone https://github.com/different-ai/openwork.git
cd openwork && git checkout dev
npm i -g pnpm@11
pnpm install

# Desktop client (pick one)

pnpm dev           # single worktree

pnpm dev:worktree  # isolated per-worktree profiles

# Backend server (run in order)

pnpm dev:den:mysql
pnpm dev:den:db-push
pnpm dev:den

# UI-only demo

pnpm dev:ui

```

## Summary

- **Clone and checkout dev** – OpenWork uses a `dev` branch for active development.
- **Use pnpm@11** – Matches the repository's pinned version for reproducible installs.
- **Single install command** – `pnpm install` resolves all monorepo dependencies.
- **Multiple launch targets** – `pnpm dev` (desktop), `pnpm dev:den` (backend), or `pnpm dev:ui` (demo).
- **Worktree isolation** – `pnpm dev:worktree` prevents profile collisions when using multiple git worktrees.

## Frequently Asked Questions

### What Node.js version does openwork require?

OpenWork requires a recent Node.js LTS version. The [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) specifies Node.js alongside pnpm as core prerequisites, though exact version pinning is handled via pnpm's engine constraints in the lockfile.

### Can I run openwork without Electron?

Yes. Use `pnpm dev:ui` to start the standalone React UI demo from [`apps/ui-demo/src/main.tsx`](https://github.com/different-ai/openwork/blob/main/apps/ui-demo/src/main.tsx). This skips the desktop client entirely and is useful for focused frontend development.

### Why does openwork need Rust installed?

Rust powers the Tauri CLI and native Electron dependencies. The Chinese translation of the README notes `cargo install tauri-cli` as a required step 【source: translated README (zh)】. Without Rust, native builds for the desktop client will fail.

### How do I debug the desktop client?

Run `pnpm dev` or `pnpm dev:worktree` and look for the CDP endpoint in the startup banner (e.g., `cdp=http://127.0.0.1:9223`). This exposes the Chrome DevTools Protocol for debugging the Electron renderer process.