Configuration Synchronization
Relevant source files
The following files were used as context for generating this wiki page:
Configuration Synchronization is the process by which OpenWork maintains consistency between the client UI, the OpenWork server, and the underlying OpenCode engine. This system ensures that changes to workspace settings, plugins, skills, and Model Context Protocol (MCP) servers are propagated across the architecture, allowing for a seamless experience whether the user is operating in a local Host mode or a remote Client mode.
Sources: ARCHITECTURE.md:46-59, packages/app/pr/openwork-orchestrator.md:6-14
System Architecture
The synchronization logic is distributed between the frontend state management and the server-side configuration handlers. OpenWork acts as a lifecycle supervisor for OpenCode, exposing APIs to read and update configuration files like opencode.json and openwork.json.
Global Sync Context
The frontend utilizes a GlobalSyncProvider to manage high-level state. It periodically refreshes global configurations, provider lists, and project metadata from the SDK client.
The diagram above shows the relationship between the frontend synchronization providers and the backend execution engines.
Sources: packages/app/src/app/context/global-sync.tsx:49-61, ARCHITECTURE.md:62-75
Workspace and Engine Lifecycle
Synchronization is triggered by specific lifecycle events, such as workspace activation or engine reloads. When a configuration change occurs (e.g., adding a plugin), the OpenWork server emits a reload event, signaling the client to refresh its state and the engine to re-read its configuration.
Synchronization Flow
- Change Detection: A user modifies configuration via the UI (e.g., PATCH
/workspace/:id/config). - Server Update: The OpenWork server updates local files like
opencode.json. - Reload Event: An event is recorded in the
ReloadEventStore. - Client Refresh: The frontend
GlobalSyncProviderdetects the event via SSE or polling and triggers a data refresh.
Sources: packages/server/src/server.ts:258-294, packages/app/src/app/context/global-sync.tsx:162-181
Server Endpoint Summary
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/workspace/:id/config | GET | Client | Retrieves resolved OpenCode and OpenWork configurations. |
/workspace/:id/config | PATCH | Client | Updates top-level configuration values in project scope. |
/workspace/:id/events | GET | Client | Polls for reload events (config, plugins, skills, MCP changes). |
/workspace/:id/engine/reload | POST | Client | Forces the OpenCode engine to dispose and re-read config. |
Sources: packages/server/src/server.ts:228-309, packages/app/pr/plugin-endpoints.md:31-48
Component Synchronization Details
Plugin and Skill Syncing
Plugins and skills are primary extensibility points. Synchronization for these involves managing the filesystem-backed opencode.json and the .opencode/skills directory.
This sequence demonstrates the coordination required to synchronize a new plugin from the UI to the execution engine.
Sources: packages/server/src/server.ts:323-348, ARCHITECTURE.md:129-132, packages/app/pr/plugin-endpoints.md:31-41
Remote Workspace Synchronization
For remote workspaces, synchronization relies on the "OpenWork Orchestrator" model. The client connects to an OpenWork host, which provides the necessary OpenCode base URL and directory paths to establish a secondary direct connection to the engine.
| Field | Source | Description |
|---|---|---|
openworkHostUrl | User Input | The primary endpoint for configuration and lifecycle management. |
opencodeBaseUrl | Host Health | The endpoint for the execution engine (usually 127.0.0.1 on the host). |
opencodeDirectory | Host Config | The specific project directory active on the host. |
Sources: packages/app/pr/openwork-orchestrator.md:16-33, packages/server/src/server.ts:215-226
Data Consistency and Approvals
To ensure safety during synchronization, particularly in remote mode, write operations (like patching config or importing workspaces) require explicit approval if not initiated locally.
- Actor Types: The system distinguishes between
hostandremoteactors. - Approval Logic: Sensitive sync actions (e.g.,
config.patch,engine.reload) trigger anApprovalRequeston the host. - Audit Logging: Every configuration mutation is recorded in an audit log (stored in
.opencode/audit.jsonl).
Sources: packages/server/src/server.ts:135-151, packages/server/src/server.ts:742-756, packages/app/pr/multi-workspace-config.md:46-52
Summary
Configuration Synchronization in OpenWork is a robust mechanism that bridges the gap between high-level user intent and low-level engine execution. By combining filesystem persistence, a centralized event store, and a structured approval process, the system ensures that workspaces remain consistent across diverse runtime environments and connectivity modes.