Build, Package & Deploy
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork utilizes a multi-layered build and deployment strategy to support its local-first, cloud-ready architecture. The project transitioned from a Tauri-based desktop shell to an Electron-based environment to improve cross-platform consistency and developer experience. The build process encompasses a React-based UI, an Electron/Tauri desktop wrapper, and a backend orchestration layer known as openwork-orchestrator.
The deployment model focuses on flexibility, allowing users to run OpenWork as a standalone desktop application, a self-hosted server, or via cloud-hosted workers. Packaging supports major operating systems including macOS (arm64/x64), Windows, and Linux (AppImage/tar.gz), with specialized support for Arch Linux users.
Sources: README.md:1-20, AGENTS.md:10-25, scripts/migration/README.md:1-15
Build System Architecture
The build pipeline is designed around a monorepo structure managed by pnpm. It separates the user interface from the desktop shell and the backend server components.
Core Components
- UI (
apps/app): A React-based frontend built using Vite. - Desktop Shell (
apps/desktop): The container for the UI, currently transitioning to Electron. - Orchestrator: A CLI host that manages the
opencodeengine andopenwork-server.
Build Process Flow
The following diagram illustrates the high-level build and packaging flow for the desktop application.
Packaging and Distribution
OpenWork is distributed through multiple channels and formats to accommodate different user environments and technical requirements.
Platform Support
| Platform | Format | Notes |
|---|---|---|
| macOS | DMG, ZIP | Supports Apple Silicon (arm64) and Intel (x64) |
| Windows | EXE | Managed via specific support plans |
| Linux | AppImage, tar.gz | WebKitGTK 4.1 required for dependencies |
| Arch Linux | Pacman / Script | Custom installation script available |
Sources: README.md:60-70, README.md:165-175, scripts/migration/README.md:46-55
Desktop Migration (Tauri to Electron)
The project is undergoing a controlled migration from Tauri to Electron. This involves specific migration scripts and safety checks to ensure user data persistence.
- Migration Release: v0.12.0 marks the last Tauri release and prompts users to move to Electron.
- Validation: Smoke tests verify that
localStoragecan be successfully transferred from Tauri to Electron via migration snapshots. - Architecture Gating: A specialized "Architecture Mismatch Gate" prevents the app from starting if the installed binary does not match the system architecture (e.g., x64 on arm64).
Sources: scripts/migration/README.md:5-25, apps/app/src/react-app/shell/architecture-mismatch-gate.tsx:10-50
Deployment Models
OpenWork supports three primary deployment modes, reflecting its "Local-first, cloud-ready" philosophy.
1. Host Mode (Local)
In this mode, the desktop app spawns and manages a local opencode server. The UI connects to this local instance via SSE (Server-Sent Events) for real-time updates.
- Runtime:
openwork(orchestrated) ordirect(spawningopencode serve). - Binding: Binds to
127.0.0.1by default for security.
2. Client Mode (Remote)
Users can connect the OpenWork UI to a remote openwork-server by URL. This is used for self-hosted instances on different hardware or shared team servers.
3. Cloud Mode
Hosted OpenWork Cloud workers are launched from the web app. These workers provide a hosted experience where the user does not need to manage local keys or hardware.
Sources: README.md:178-200, AGENTS.md:15-20
Continuous Integration and Testing
The build process is integrated with GitHub Actions for automated building, testing, and preview releases.
Test Suites
- End-to-End (E2E): Exercised via
pnpm test:e2e. - UI Evals: Human-readable or LLM-driven scenarios against live instances to verify UI behavior.
- Type Checking: Verified via
pnpm typecheck.
CI Workflow Diagram
Release Runbook Requirements
When performing a release or opening a Pull Request, specific guidelines must be followed:
- Release Bumping: Version numbers must be synchronized across five specific files.
- Evidence of Flow: PRs should include video or screenshots showing successful end-to-end execution.
- Clean Tree: Migration and release scripts refuse to run on dirty working trees.
Sources: AGENTS.md:35-45, scripts/migration/README.md:65-75
Conclusion
The build and deployment infrastructure of OpenWork emphasizes reliability and platform flexibility. By transitioning to Electron and implementing robust migration and architecture-checking mechanisms, the project ensures a consistent environment for agentic workflows across local and remote contexts. The multi-modal deployment allows OpenWork to scale from a single developer's machine to a shared enterprise cloud environment.