Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork is an open-source alternative to Claude Cowork, designed as a desktop application that orchestrates agentic workflows. It serves as a control surface for local and remote agents, skills, and Model Context Protocol (MCP) servers. The system is built with a local-first philosophy, allowing users to run complex AI operations on their machines while maintaining compatibility with cloud-hosted workers.
Sources: AGENTS.md:3-13, README.md:1-5
The project is currently transitioning from a Solid-based UI to a React-based architecture, organized into domain-specific modules. It leverages a multi-mode execution model where the UI acts as a client to an underlying server stack composed of OpenCode, an OpenWork server, and an optional router.
Sources: apps/app/src/react-app/ARCHITECTURE.md:3-6, README.md:104-115
System Orchestration Modes
OpenWork operates in two primary execution modes to manage agentic workflows:
Host Mode (Local)
In Host Mode, OpenWork runs a local host stack that orchestrates the core components. It utilizes openwork-orchestrator to manage opencode and openwork-server. A fallback "direct" runtime allows the desktop app to spawn opencode serve directly on a free local port.
Sources: README.md:104-110
Client Mode (Remote)
In Client Mode, the UI connects to an existing OpenCode server via URL. This allows the application to interact with hosted OpenWork Cloud workers or other remote instances.
Sources: README.md:38-40, AGENTS.md:12
The diagram shows the relationship between the UI, the OpenWork Server, and the underlying OpenCode engine.
Sources: README.md:104-123
Frontend Architecture
The frontend is located in apps/app/src/react-app/ and follows a domain-driven design. This structure ensures that feature-scoped code is isolated into logical modules.
Top-Level Layout
- Shell: App bootstrap, providers composition, and startup effects.
- Kernel: App-wide state and provider contracts (replacing legacy contexts).
- Domains: Feature-specific logic (e.g.,
session,workspace,settings). - Infra: React-only runtime infrastructure like the TanStack Query client.
Sources: apps/app/src/react-app/ARCHITECTURE.md:8-25
Data and State Flow
State management is handled through a tiered provider stack and a Zustand store for React components. The UI communicates with the server using the @opencode-ai/sdk/v2/client.
| Provider | Purpose |
|---|---|
ServerProvider | Manages server connection state |
GlobalSDKProvider | Exposes the OpenCode SDK |
QueryClientProvider | Handles TanStack Query caching |
PlatformProvider | Abstracted logic for Tauri vs. Web environments |
Sources: apps/app/src/react-app/ARCHITECTURE.md:41-65, README.md:117-123
Workspace and Agent Configuration
Workspaces are initialized with specific configuration files located in the .opencode/ directory of a project folder. The initialization process ensures necessary plugins and default agents are present.
Key Configuration Files
opencode.json: Manages plugins and default agent settings. It supports both project-scope and global-scope configurations.openwork.md: Defines the default agent behavior, including instructions for browser control and artifact handling..openwork.jsonc: Contains workspace-specific settings like name, creation date, and authorized roots.
Sources: README.md:130-142, apps/server/src/workspace-init.ts:80-112
Sequence of workspace initialization when a user selects a folder.
Sources: apps/server/src/workspace-init.ts:182-198, README.md:112-115
Execution and Tooling
Skills and Plugins
Skills are portable folders containing SKILL.md files. They extend the application with specialized workflows or tool integrations. Plugins are the native way to extend the underlying OpenCode engine, such as the opencode-chrome-devtools plugin used for browser automation.
Sources: apps/app/src/app/data/skill-creator.md:10-14, apps/server/src/workspace-init.ts:13-14
Artifact Handling
OpenWork can preview, edit, and download deliverables created by agents. Supported artifacts include:
- Markdown (
.md): Rendered in-app. - Spreadsheets (
.csv,.xlsx): Displayed in a grid renderer. - HTML (
index.html): Previewed in a sandboxed environment.
Sources: apps/server/src/workspace-init.ts:16-25, apps/server/src/artifact-files.e2e.test.ts:71-90
Testing and Validation
OpenWork utilizes "Evals"—human-readable scenarios executed against a live instance. These verify end-to-end behavior across the OpenCode engine, the OpenWork server, and the React UI. Testing tools include browser automation primitives (e.g., browser_click, browser_snapshot) to simulate user interactions.
Sources: evals/README.md:3-10, evals/README.md:52-60
Conclusion
The OpenWork architecture is designed for extensibility and portability, allowing agentic workflows to be shared across teams via simple links. By leveraging a local-first server-client model, it provides an auditable and permissioned environment for running AI agents with 50+ supported LLMs.
Sources: AGENTS.md:10-25, README.md:46-52