Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• PRODUCT.md
• ARCHITECTURE.md
• AGENTS.md
• INFRASTRUCTURE.md
• packages/app/src/i18n/locales/en.ts
• packages/desktop/src-tauri/tauri.conf.json

OpenWork is an extensible, open-source desktop application designed to provide a "productized" experience for agentic workflows built on top of the OpenCode engine. The installation and setup process is designed to support two primary operational modes: Host Mode, where the user runs the OpenCode engine locally, and Client Mode, where the application connects to a remote OpenCode server.

The system is built using a modern stack involving Tauri 2.x for the desktop/mobile shell, SolidJS for the frontend, and a Rust backend for system-level integrations and process management. Successful setup requires the presence of the OpenCode CLI, which serves as the core execution engine for all agentic tasks.

Sources: README.md:1-15, AGENTS.md:30-40, ARCHITECTURE.md:25-35

System Requirements

Before installing OpenWork, ensure the following dependencies are installed on your system:

Dependency	Purpose	Requirement Details
Node.js	JavaScript Runtime	Required for frontend development and pnpm
pnpm	Package Manager	Used for managing the monorepo dependencies
Rust Toolchain	Backend Compiler	Installed via rustup; required for Tauri
Tauri CLI	Desktop Packaging	Installed via cargo install tauri-cli
OpenCode CLI	Execution Engine	Must be available on system PATH

Sources: README.md:118-128, AGENTS.md:30-40

Core Operational Modes

The installation workflow varies depending on whether the user intends to host the engine or connect remotely.

Host Mode (Desktop/Server)

In this mode, OpenWork spawns an OpenCode server process locally (typically binding to 127.0.0.1:4096). The application uses the project folder selected by the user as the working directory.

Client Mode (Mobile/Remote)

OpenWork acts as a remote controller, connecting to an existing OpenCode server. This setup allows mobile devices or secondary computers to monitor runs and approve permissions without running the full engine locally.

The following diagram illustrates the initial launch flow where the user selects their operational mode:

Development Setup

To set up the project for local development or to build from source, follow these steps within the repository root:

1. Install Dependencies

pnpm install

This command installs the necessary packages for the packages/app (UI) and packages/desktop (shell) modules.

2. Execution Commands

OpenWork provides several scripts for different development scenarios:

• Desktop Development: pnpm dev (Runs both UI and Tauri shell)
• Web UI Only: pnpm dev:ui (Runs the SolidJS app in the browser)
• Build: pnpm build (Produces the production distribution)

Sources: README.md:130-146, packages/desktop/src-tauri/tauri.conf.json:7-12

Infrastructure Principles

The setup process adheres to specific infrastructure guidelines to ensure portability and observability:

1. CLI-First: Every component must be runnable via a single CLI command. OpenWork's UI wraps these commands but does not lock them out.
2. Sidecar Composable: Components like openwork-server and owpenbot can run as sidecars.
3. Local-First: The system defaults to local execution, falling back to read-only or guidance modes if the engine is missing.
4. Authorized Scoping: All filesystem access is strictly scoped to workspace roots explicitly authorized by the user during setup.

Sources: INFRASTRUCTURE.md:7-35, PRINCIPLES.md:13-20

OpenCode SDK Integration

OpenWork integrates with the OpenCode engine via the @opencode-ai/sdk/v2. This SDK allows the application to:

• Connect to the server (using createOpencode for Host mode or createOpencodeClient for Client mode).
• Subscribe to SSE (Server-Sent Events) for real-time updates on task progress and tool calls.
• Manage sessions and permission requests.

Configuration Snippet (Host Mode)

import { createOpencode } from "@opencode-ai/sdk/v2";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  timeout: 5000,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

Sources: ARCHITECTURE.md:46-60, README.md:158-165

Workspace Onboarding (Host)

When setting up a new local workspace, the application performs a series of initialization steps:

1. Safety Overview: Presents a welcome and safety briefing to the user.
2. Folder Selection: The user selects a primary workspace folder.
3. Permissions: The user specifies "Allowed Folders" for the engine to access.
4. Health Verification: The system runs global.health() to ensure the OpenCode CLI is responsive.
5. Test Run: An initial session.create() call is made to verify the model configuration.

Sources: PRODUCT.md:83-91, packages/app/src/i18n/locales/en.ts:430-450

Troubleshooting Linux/Wayland

For users on Linux (specifically Wayland/Hyprland), the WebKitGTK renderer may encounter errors such as Failed to create GBM buffer. To resolve this, set the following environment variables before launching:

• WEBKIT_DISABLE_DMABUF_RENDERER=1
• WEBKIT_DISABLE_COMPOSITING_MODE=1

Sources: README.md:195-205

The successful installation and setup of OpenWork result in a system where agentic workflows are auditable, permissioned, and easily shared across a team. By strictly separating the UI layer (OpenWork) from the execution engine (OpenCode), the project maintains high stability and flexibility for both developers and non-technical end-users.

Sources: README.md:10-25, INFRASTRUCTURE.md:40-45