Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork is a local-first, cloud-ready control surface for agentic work, designed as an open-source alternative to Claude Cowork. It allows users to run local and remote agent workflows, integrate Model Context Protocol (MCP) servers, and manage skills through a unified desktop or server interface. The system is built on the OpenCode runtime, ensuring that any capability supported by OpenCode is natively available within OpenWork.
The setup process involves preparing the local environment with specific runtimes (Node.js, Bun, Rust), installing the OpenCode CLI, and initializing a workspace folder. Users can choose between Host mode, which runs the OpenCode stack locally, and Client mode, which connects to a remote OpenWork server.
Sources: README.md:1-15, AGENTS.md:3-15, ee/apps/landing/public/llms.txt:3-10
System Requirements & Prerequisites
OpenWork requires a specific set of tools for both execution and development. The core runtime relies on Node.js and the Rust toolchain for the Tauri-based desktop shell.
Core Dependencies
| Requirement | Description |
|---|---|
| Node.js + pnpm | Required for package management and running the UI apps. |
| Bun 1.3.9+ | Required for server-side logic and testing. |
| Rust Toolchain | Required to build and run the Tauri desktop shell. |
| OpenCode CLI | The underlying agentic engine. Must be available on system PATH. |
| Tauri CLI | Required for desktop-specific development (cargo install tauri-cli). |
Sources: README.md:120-140, README.md:144-150
Platform Specifics
- macOS: Requires Xcode Command Line Tools.
- Linux: Requires WebKitGTK 4.1 development packages (
webkit2gtk-4.1andjavascriptcoregtk-4.1). - Windows: Access is currently handled through specific support plans.
Sources: README.md:75-80, README.md:150-155
Installation Flow
The installation process varies depending on whether you are using the pre-built desktop app or setting up the development environment.
Developer Setup
- Clone the repository and checkout the
devbranch. - Install dependencies using
pnpm install. - Verify runtimes: Ensure
bun,pnpm, andtauriversions are correct. - Initialize OpenCode: The installation script for OpenCode can be run via curl.
# Example OpenCode installation for Arch Linux users
curl -fsSL https://opencode.ai/install | bash -s -- --version "$(node -e "const fs=require('fs'); ...")" --no-modify-path
Sources: README.md:158-185
Quick Start Diagram
The following diagram illustrates the initial setup and runtime selection flow for a new user.
The diagram shows the branching path between end-users using the cloud-guided flow and developers setting up the environment manually.
Sources: ee/apps/landing/app/download/page.tsx:65-85, README.md:120-135, apps/server/src/workspace-init.ts:168-180
Workspace Initialization
When a project folder is selected, OpenWork executes a series of initialization steps to ensure the directory is a valid OpenCode/OpenWork workspace. This logic is handled by the ensureWorkspaceFiles function.
Initialization Components
- opencode.jsonc: Created or updated to include the schema and default plugins like
opencode-chrome-devtools. - .opencode/openwork.json: Stores OpenWork-specific metadata including versioning, creation timestamps, and authorized roots.
- .opencode/agents/openwork.md: A default agent file is created, providing instructions for the agent on how to use the browser and artifacts.
Sources: apps/server/src/workspace-init.ts:114-165, apps/server/src/workspace-init.test.ts:14-25
Workspace Verification Sequence
The sequence shows how the server proactively initializes configuration files and notifies the UI if a reload is required to activate new agents or plugins.
Sources: apps/server/src/workspace-init.ts:168-185, evals/react-session-flows.md:160-180
Runtime Modes
OpenWork operates in two primary execution modes which determine how the UI communicates with the OpenCode engine.
| Mode | Description | Default Connectivity |
|---|---|---|
| Host Mode | Runs the host stack locally. Orchestrates opencode, openwork-server, and opencode-router. | Binds to 127.0.0.1 |
| Client Mode | Connects the desktop UI to an existing OpenCode server via a remote URL. | Requires a token |
| Orchestrator | A CLI-only mode for running the server without the desktop UI. | Command: openwork start |
Sources: README.md:189-205, README.md:28-35, AGENTS.md:10-15
Development Environment Variables
For developers, OpenWork provides specific flags to isolate development state from personal data.
OPENWORK_DEV_MODE=1: Automatically enabled bypnpm dev. It forces the use of an isolated OpenCode state (usually inopenwork-dev-data).OPENWORK_ELECTRON_REMOTE_DEBUG_PORT: Defaults to9222. Used by the agent to connect to the built-in browser via Chrome DevTools Protocol (CDP).
Sources: README.md:175-180, apps/server/src/workspace-init.ts:133-136
OpenWork is designed to be "ejectable," meaning all configurations are stored in standard JSON format in the workspace, allowing users to transition to CLI tools or other GUIs without data lock-in.
Sources: AGENTS.md:15-20, README.md:210-220