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

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 【source: translated README (zh) → "Tauri CLI: cargo install tauri-cli"】, while Node.js and pnpm requirements are documented in the 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:

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:

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:

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:

# Standard development mode

pnpm dev

Worktree-Isolated Development

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

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 【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

# Launch MySQL container

pnpm dev:den:mysql

# Push schema migrations

pnpm dev:den:db-push

Start the Server and UI

pnpm dev:den

This brings up the HTTP server (apps/server/src/server.ts) and its associated UI. Server-side workspace logic resides in 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:

pnpm dev:ui

This launches the minimal React application from 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, apps/server/src/workspaces.ts
apps/ui-demo/	Standalone React UI	apps/ui-demo/src/main.tsx
dev/scripts/	Build and release helpers	Migration and diagnostic tools

The dev/package.json serves as the command central for all local development scripts 【source: dev/package.json】.

Complete Installation Command Reference

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

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