High-Level Architecture

Relevant source files

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

• ARCHITECTURE.md
• INFRASTRUCTURE.md
• PRODUCT.md
• README.md
• packages/app/pr/openwork-orchestrator.md
• packages/server/src/server.ts

OpenWork is an experience layer and lifecycle supervisor built on top of the OpenCode engine. It is designed to transform complex agentic workflows into a clean, guided product experience for both technical and non-technical users. The system follows a local-first philosophy while maintaining a "Client-Server" split that enables remote control from mobile devices or other thin clients.

Sources: PRODUCT.md:32-34, INFRASTRUCTURE.md:4-6, ARCHITECTURE.md:46-50

System Overview

The architecture is centered around the separation of concerns between the OpenCode Engine (the execution core) and the OpenWork UI/Server (the orchestration and UX layer). OpenWork acts as a supervisor for the OpenCode process, managing its lifecycle and exposing its capabilities through a slick, real-time interface.

Core Components

Component	Description	Primary Technology
OpenCode Engine	The underlying agentic engine that executes tasks, tool calls, and manages sessions.	OpenCode CLI
OpenWork Server	A Bun-based server providing filesystem-backed configuration, approvals management, and orchestrator APIs.	Bun / TypeScript
OpenWork UI	The frontend application providing task management, real-time streaming, and visual execution plans.	SolidJS + TailwindCSS
Desktop Shell	The native wrapper providing system-level access, such as folder pickers and sidecar process management.	Tauri 2.x

Sources: INFRASTRUCTURE.md:43-52, ARCHITECTURE.md:52-59, packages/server/src/server.ts:32-40, README.md:120-125

Runtime Modes

OpenWork operates in two primary runtime modes to facilitate both local execution and remote orchestration.

Mode A: Host (Desktop/Server)

In Host mode, OpenWork runs locally on a desktop or laptop. It spawns the OpenCode server as a sidecar process and connects to it via loopback. The OpenWork UI then interacts with this local engine through the official SDK.

Mode B: Client (Remote Controller)

In Client mode, the application (typically running on iOS/Android or a browser) connects to an existing OpenWork Host. The host provides the client with OpenCode connection details and active workspace metadata.

The diagram shows the relationship between components in both Host and Client modes.
Sources: ARCHITECTURE.md:46-61, packages/app/pr/openwork-orchestrator.md:13-16

Orchestration and API Contract

The OpenWork Server acts as the orchestrator, managing workspace activation and security approvals. It exposes specific endpoints for health monitoring and capability discovery.

OpenWork Orchestrator APIs

• GET /health: Returns version and health status. Used by clients to distinguish between an OpenWork host and a direct OpenCode connection.
• GET /workspaces: Returns information about the active workspace, including the OpenCode base URL and directory.
• GET /capabilities: Reports available features like skills, plugins, and MCP read/write access.
• POST /workspace/:id/engine/reload: Triggers an engine reload by calling the OpenCode /instance/dispose endpoint.

Sources: packages/app/pr/openwork-orchestrator.md:43-61, ARCHITECTURE.md:108-112, packages/server/src/server.ts:180-210

Security and Approvals Flow

OpenWork enforces a strict folder authorization model. All filesystem access is scoped to explicit workspace roots. When a remote client or agent requests a sensitive operation (like writing a file), the OpenWork Server intercepts the request for host approval.

This sequence illustrates how the OpenWork Server gates configuration updates through a manual approval process on the host.
Sources: packages/server/src/server.ts:114-125, packages/server/src/server.ts:640-650, ARCHITECTURE.md:135-140

Integration with OpenCode Primitives

OpenWork leverages native OpenCode primitives rather than building custom abstractions. This ensures parity between the CLI and the UI.

1. Sessions: Mapped to "Task Runs." The UI uses client.session.prompt() and subscribes to SSE /event for real-time updates.
2. Steps: Every tool call is rendered as a step in a timeline, derived from reasoning and tool event parts.
3. Skills: Stored as markdown files in .opencode/skills/. OpenWork manages these via opkg or direct filesystem edits.
4. Plugins: Configured via opencode.json in the workspace. OpenWork provides a management UI that reads and writes this configuration.

Sources: ARCHITECTURE.md:12-44, ARCHITECTURE.md:65-90, README.md:132-140, PRODUCT.md:44-60

Infrastructure Principles

The architecture adheres to several core infrastructure principles:

• CLI-first: Every component must be runnable via a standalone CLI command (e.g., openwork-server, opencode).
• Unix-like Interfaces: Composable boundaries using JSON over stdout and environment variables.
• Local-first: Execution defaults to the local machine, with graceful degradation when remote hosts are offline.
• Portable Configuration: Configurations are filesystem-backed (typically .json or .md) to allow for easy sharing and auditing.

Sources: INFRASTRUCTURE.md:8-30, PRINCIPLES.md:16-20