Desktop Shell & System Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Desktop Shell and System Integration module serves as the primary bridge between the OpenWork React-based user interface and the underlying host operating system. This system is responsible for orchestrating the local runtime environment, managing file system access through the Tauri framework, and ensuring the application runs on the correct hardware architecture. It allows OpenWork to function as a "local-first" application while maintaining compatibility with cloud-based worker services.
The integration ensures that core agentic capabilities—such as file manipulation, browser automation, and local execution—are handled securely within the user's infrastructure. By leveraging a desktop shell, the application can bypass web-only limitations, providing direct access to the opencode CLI and local workspace folders.
Sources: README.md:1-15, AGENTS.md:1-15, apps/app/src/react-app/ARCHITECTURE.md:1-20
Architecture & Runtime Orchestration
OpenWork's desktop architecture is built upon a "Host mode" and a "Client mode" paradigm. In Host mode, the desktop shell manages a local stack that orchestrates several underlying services to provide a seamless agentic experience.
Local Runtime Components
The desktop application typically manages three primary sub-processes when running locally:
- OpenCode CLI: The core engine for agentic workflows and tool execution.
- OpenWork Server: A local Bun-based server that manages session sync, audit logs, and the lifecycle of OpenCode.
- OpenCode Router: An optional component for managing multiple tool or model routing paths.
The following diagram illustrates the relationship between the Desktop UI and these local services:
The UI communicates with the local OpenWork server using the @opencode-ai/sdk/v2/client, which facilitates session management, prompt submission, and real-time SSE (Server-Sent Events) updates.
Sources: README.md:144-162, apps/app/src/react-app/ARCHITECTURE.md:65-75
System Verification & Safety Gates
A critical component of the system integration is the Architecture Mismatch Gate. This safety mechanism prevents the application from booting if there is a discrepancy between the compiled application architecture and the host system's hardware (e.g., running an x64 build on an ARM64 macOS system).
Architecture Mismatch Logic
The application utilizes a specific React component, ArchitectureMismatchGate, to intercept the boot process. It queries the system bridge via window.__OPENWORK_ELECTRON__?.system?.getArchitectureInfo. If a mismatch is detected, the application blocks standard UI rendering and directs the user to download the correct build.
Security & Permission Boundaries
OpenWork operates under a "Local-first" security model. Key security facts regarding system integration include:
| Feature | Desktop Implementation |
|---|---|
| Data Residency | All code, API keys, and prompts stay on the local machine unless explicitly connected to a remote LLM provider. |
| File Permissions | Defined in Tauri capability files (e.g., apps/desktop/src-tauri/capabilities/default.json). |
| LLM Gateway | Direct traffic between the user and LLM provider; no middle proxy is used for self-hosted deployments. |
| Networking | Host mode binds to 127.0.0.1 by default for local security. |
Sources: ee/apps/landing/components/landing-trust.tsx:90-115, README.md:164-167, README.md:200-205
File System & Workspace Integration
System integration is centered around the concept of a "Project Folder." When a user selects a folder via the Tauri dialog, the desktop shell initializes that directory as a workspace.
Workspace Components
- Folder Picker: Uses the Tauri dialog plugin to grant the application access to specific filesystem nodes.
- opencode.json: A configuration file stored in either the project root (
<workspace>/opencode.json) or the global config directory (~/.config/opencode/). This file defines plugins and local skill availability. - Local Cache: Stored in isolated data directories (e.g.,
openwork-dev-dataduring development) to ensure state isolation.
Sources: README.md:164-167, README.md:169-180, README.md:230-240
Development & Debugging Tools
The desktop shell provides specialized hooks for developer introspection. These are accessible via the Settings -> Debug menu in the UI.
| Debug Tool | Description |
|---|---|
| Diagnostics Bundle | Export of sanitized runtime state, including version info and PID. |
| Developer Log Stream | Real-time capture of app, workspace, and session events. |
| CDP Exposure | In development, the Electron/Tauri shell exposes a Chrome DevTools Protocol endpoint (typically at http://127.0.0.1:9823) for automated testing and inspection. |
Sources: evals/README.md:10-25, apps/app/src/i18n/locales/en.ts:settings_section
Summary
Desktop Shell & System Integration in OpenWork is the foundational layer that enables high-performance, local agentic workflows. By orchestrating the OpenCode engine through a local server and enforcing strict architecture and security gates, the system provides a robust environment for users to interact with local files and tools using AI, while maintaining the flexibility to connect to cloud services when required.
Sources: README.md:1-20, AGENTS.md:1-10