Development Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
Setting up the OpenWork development environment requires configuring a multi-layered stack comprising a SolidJS frontend, a Rust-based Tauri desktop shell, and the OpenCode engine. The project is designed to be "local-first," allowing developers to run the full stack on a single machine or connect specialized clients to remote host servers.
The environment is built around OpenCode, which serves as the core execution engine. Developers can contribute to the UI in packages/app, the desktop integration in packages/desktop, or the standalone server in packages/server.
Sources: README.md:1-20, AGENTS.md:54-69, ARCHITECTURE.md:46-55
System Requirements
Before initializing the repository, the following toolchains must be installed on the host system:
| Dependency | Purpose | Installation/Requirement |
|---|---|---|
| Node.js + pnpm | Frontend and Workspace management | Core package manager for the monorepo |
| Rust Toolchain | Tauri desktop shell compilation | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs |
| Tauri CLI | Desktop app orchestration | cargo install tauri-cli |
| OpenCode CLI | Core agentic engine | Must be available on PATH as opencode |
Sources: README.md:120-130, AGENTS.md:38-44
Repository Initialization
The project uses a monorepo structure managed by pnpm. Initial setup involves installing all dependencies across the workspace.
# Clone and install dependencies
git clone <repository-url>
cd openwork
pnpm install
During initialization, the build system prepares sidecars and the frontend distribution. The tauri.conf.json defines a beforeDevCommand that ensures the sidecar environment and UI dev server are ready.
Sources: README.md:132-135, packages/desktop/src-tauri/tauri.conf.json:7-12
Development Runtime Modes
OpenWork supports two primary development workflows: Desktop and Web-only.
Desktop Development
This is the standard mode using Tauri. It provides the full native experience, including folder picker dialogs and local OpenCode process supervision.
pnpm dev
Web UI Development
For iterating quickly on the SolidJS frontend without compiling the Rust shell.
pnpm dev:ui
Development Architecture Flow
The following diagram illustrates how the development environment components interact when running in Host mode.
The diagram shows the relationship between the SolidJS frontend, the Tauri Rust shell, and the spawned OpenCode/OpenWork sidecar processes.
Sources: README.md:139-160, ARCHITECTURE.md:52-64, packages/desktop/src-tauri/tauri.conf.json:34-38
Core Development Commands
The root package.json provides several scripts to manage the development lifecycle across the packages/app and packages/desktop directories.
| Command | Action |
|---|---|
pnpm dev | Starts the full Tauri desktop application in development mode |
pnpm dev:ui | Starts only the SolidJS frontend (typically on port 5173) |
pnpm typecheck | Runs TypeScript validation across the workspace |
pnpm build | Compiles the production desktop application |
pnpm build:ui | Builds the frontend assets for distribution |
pnpm test:e2e | Executes end-to-end tests |
Sources: README.md:188-195, packages/desktop/src-tauri/tauri.conf.json:10-12
Project Structure for Contributors
The repository is organized to separate the UI, desktop shell, and headless server components.
packages/app/: SolidJS + TailwindCSS frontend code.packages/desktop/: Tauri configuration and Rust core logic.packages/server/: The standalone OpenWork server (Node/Bun).packages/headless/: CLI host orchestrator for running without a UI.
Sources: AGENTS.md:54-69, INFRASTRUCTURE.md:73-83
Sidecar Management
OpenWork relies on external binaries bundled as sidecars. During development, these are managed through the Tauri configuration. The tauri.conf.json file explicitly lists these binaries which are required for the "Host" mode functionality.
"externalBin": [
"sidecars/opencode",
"sidecars/openwork-server",
"sidecars/owpenbot"
]
Sources: packages/desktop/src-tauri/tauri.conf.json:34-38, packages/app/progress.json:11-13
Verification and Quality Checks
To ensure the environment is correctly set up, developers should verify the following:
- OpenCode Availability: Ensure
opencode --versionworks in the terminal. - SDK Connectivity: The frontend uses
@opencode-ai/sdk/v2/client. Ensure the UI can connect to the loopback address127.0.0.1:4096in Host mode. - Type Integrity: Run
pnpm typecheckto verify cross-package type compatibility. - Health Check: Access the
/healthendpoint of the OpenWork server (default port 8787) or the OpenCode server (default port 4096).
Sources: README.md:155-165, AGENTS.md:88-100, [INFRASTRUCTURE. INFRASTRUCTURE.md:23-28
Conclusion
Setting up the OpenWork development environment involves synchronizing a Node.js monorepo with Rust-based desktop tooling. By leveraging sidecars and the OpenCode SDK, the project maintains a portable and extensible architecture suitable for both local development and remote server deployments.