Workspaces & Context
Relevant source files
The following files were used as context for generating this wiki page:
Workspaces in OpenWork represent the primary organizational unit for agentic workflows, encapsulating project folders, configurations, and environment settings. A workspace defines the authorized boundary within which the OpenCode engine operates, allowing users to switch between different project contexts—such as local folders or remote servers—while maintaining isolated session histories, skills, and permissions.
The system is designed to facilitate "Host" and "Client" modes, where a host manages the local lifecycle of the OpenCode engine and a client connects to these hosts to orchestrate tasks. This architecture ensures that context is preserved across devices while enforcing strict security boundaries through folder authorization and explicit user approval for file access.
Sources: PRODUCT.md, ARCHITECTURE.md:46-56, packages/app/pr/multi-workspace-config.md:7-14
Workspace Architecture
OpenWork utilizes a dual-layered architecture for workspace management, separating the frontend UI state from the backend execution engine.
Runtime Modes
The system operates in two primary modes that dictate how workspace context is established:
- Host Mode: The application runs locally, starts the OpenCode server on loopback (127.0.0.1:4096), and authorizes specific local directories.
- Client Mode: The application acts as a remote controller, connecting to a "Host" via a secure transport. The host provides the OpenCode connection details (Base URL and directory) for the active workspace.
Sources: ARCHITECTURE.md:58-75, packages/app/pr/openwork-orchestrator.md:12-25
Workspace Types
| Type | Description | Key Attributes |
|---|---|---|
| Local | A directory on the user's machine authorized for OpenCode. | path, preset |
| Remote (OpenWork) | Context provided by an OpenWork Host server. | openworkHostUrl, openworkWorkspaceId |
| Remote (OpenCode) | A direct connection to a standalone OpenCode instance. | baseUrl, directory |
Sources: packages/app/src/app/context/workspace.ts:133-157, packages/desktop/src-tauri/src/commands/workspace.rs:188-212
Data Flow & Lifecycle
The lifecycle of a workspace involves bootstrapping, activation, and engine synchronization. When a workspace is activated, the application must ensure the underlying OpenCode engine is targeting the correct directory and using the appropriate configuration.
Workspace Activation Flow
The following diagram illustrates the process of switching the active workspace, which may involve restarting the local engine or re-establishing a remote connection.
Configuration Synchronization
Workspace configuration is stored in two primary files located within the project's .opencode directory:
opencode.json: Defines engine-level settings, including plugin lists and model configurations.openwork.json: Stores UI-specific context, such asauthorizedRootsfor the folder picker.
Sources: packages/server/src/server.ts:184-188, packages/desktop/src-tauri/src/commands/workspace.rs:326-340
Security & Folder Authorization
OpenWork enforces a strict "least privilege" model. The application only interacts with folders that the user has explicitly authorized.
Authorization Layers
- Layer 1 (UI Authorization): Users select allowed roots via a native OS picker. These are saved in the
authorized_rootsarray inopenwork.json. - Layer 2 (Server Enforcement): The OpenWork server validates every request against the authorized roots list before performing filesystem operations.
Sources: ARCHITECTURE.md:162-178, packages/server/src/server.ts:511-519, packages/desktop/src-tauri/src/commands/workspace.rs:311-324
Import & Export Mechanism
To facilitate sharing and portability, OpenWork supports exporting workspace configurations (excluding secrets and local paths) into a compressed .openwork-workspace archive.
Export Logic
The export process collects:
opencode.json(Engine config).opencode/skills/(Custom behaviors).opencode/commands/(Reusable prompts)- A
manifest.jsoncontaining metadata and checksums.
Secrets such as .env files, .key, and .pem files are explicitly excluded from the archive.
Sources: packages/desktop/src-tauri/src/commands/workspace.rs:408-460, packages/app/pr/multi-workspace-config.md:41-46
API Endpoints for Context Management
| Method | Endpoint | Description |
|---|---|---|
GET | /workspaces | Lists available workspaces on the host. |
POST | /workspaces/:id/activate | Sets the active workspace for the server instance. |
PATCH | /workspace/:id/config | Updates opencode.json or openwork.json. |
POST | /workspace/:id/engine/reload | Forces the OpenCode engine to re-read configuration. |
Sources: packages/server/src/server.ts:153-210, packages/server/README.md:38-60
Conclusion
The Workspace and Context system provides a robust framework for managing diverse project environments within OpenWork. By combining local engine supervision with remote orchestration capabilities and strict folder authorization, it enables safe and scalable agentic workflows across different machine boundaries.
Sources: ARCHITECTURE.md:58-65, packages/app/pr/multi-workspace-config.md:65-68