Workspace Management
Relevant source files
The following files were used as context for generating this wiki page:
Workspace Management in OpenWork is the system responsible for orchestrating local project environments and remote worker connections. It provides a standardized interface for the OpenWork client to interact with diverse execution environments, ensuring that agents have consistent access to files, configurations, and specialized "skills" regardless of where the compute occurs.
The system encompasses the full lifecycle of a workspace: from the initial onboarding and directory selection to the automated injection of OpenCode configurations and the eventual synchronization of remote worker states. By treating local folders and remote servers as unified "workspaces," the platform enables seamless transitions between local development and cloud-ready agentic workflows.
Workspace Architecture and Types
OpenWork distinguishes between two primary categories of workspaces, each handled by distinct registration and initialization logic.
Local Workspaces
Local workspaces are anchored to a specific directory on the user's filesystem. When a local workspace is created, the server ensures the existence of a .opencode hidden directory and populates it with baseline configuration files. This setup allows the local opencode engine to treat the folder as a project root.
Sources: [apps/server/src/server.ts:713-731](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L713-L731), [apps/server/src/workspace-init.ts:169-183](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-init.ts#L169-L183)
Remote Workspaces
Remote workspaces connect to hosted OpenWork Cloud workers or self-hosted OpenCode instances. These environments are defined by a baseUrl and an access token. The management system handles "discovery" for these workspaces, often stripping mount points from URLs to resolve the underlying API surface.
Sources: [apps/server/src/server.ts:748-812](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L748-L812), [apps/server/src/server.ts:169-195](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L169-L195)
Workspace Creation Flow
The following diagram illustrates the logical path taken when adding a new workspace to the system.
The creation flow ensures that every environment is properly "bootstrapped" with the necessary agent guidance and plugin configurations before an agent starts work.
Sources: [apps/server/src/server.ts:713-812](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L713-L812), [apps/server/src/workspace-init.ts:169-183](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-init.ts#L169-L183)
Workspace Initialization and Bootstrapping
When a workspace is initialized or activated, the ensureWorkspaceFiles utility performs several critical setup tasks to prepare the environment for agentic work.
- Configuration Injection: It creates
opencode.jsoncif missing, setting thedefault_agentto "openwork" and enabling theopencode-chrome-devtoolsplugin for browser automation. - Agent Guidance: It generates or patches
.opencode/agents/openwork.md, injecting standard instructions for handling OpenWork Artifacts (Markdown, CSV, Excel) and browser tools. - Local State: It manages
openwork.json, which tracks workspace metadata such as creation time, presets (e.g., "starter"), and authorized roots. - Authorized Roots: For security, the server maintains a list of
authorizedRoots. Local workspaces are only accessible if they reside within these resolved paths.
Sources: [apps/server/src/workspace-init.ts:169-183](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-init.ts#L169-L183), [apps/server/src/workspace-init.ts:25-50](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-init.ts#L25-L50), [apps/server/src/server.ts:1145-1155](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L1145-L1155)
Workspace Initialization Logic
The sequence below shows how the server prepares a local directory upon activation.
Sources: [apps/server/src/server.ts:854-878](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L854-L878), [apps/server/src/workspace-init.ts:169-183](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-init.ts#L169-L183)
Data Models and Registry
Workspaces are persisted in the server's configuration file (usually config.json in the data directory). The WorkspaceInfo interface defines the core properties of a workspace.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., ws_... for local, rem_... for remote). |
name | string | Human-readable label for the sidebar. |
path | string | Local absolute path or remote directory hint. |
workspaceType | enum | Either local or remote. |
baseUrl | string | (Remote only) The API endpoint for the worker. |
preset | string | Template identifier (e.g., starter, remote). |
authorizedRoots | string[] | Paths allowed for filesystem operations. |
Sources: [apps/server/src/types.ts](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/types.ts), [apps/server/src/server.ts:1107-1132](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L1107-L1132)
Management Operations
The Workspace Management system provides several API endpoints for ongoing maintenance of project environments.
Renaming and Metadata
Users can update the displayName of a workspace. This updates the registry in the server's configuration and triggers a reload event so the UI sidebar reflects the change immediately.
Sources: [apps/server/src/server.ts:814-852](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L814-L852), [apps/app/src/react-app/shell/session-route.tsx:1273-1296](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/app/src/react-app/shell/session-route.tsx#L1273-L1296)
Import and Export
Workspaces can be exported as portable JSON bundles containing sanitized opencode configs, openwork metadata, skills, and specific project files. The import process provides a "preview" fingerprint, allowing users to review changes (Create, Update, Delete) before applying them to the filesystem.
Sources: [apps/server/src/workspace-import-preview.ts:153-200](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/workspace-import-preview.ts#L153-L200), [apps/server/src/server.ts:1072-1100](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L1072-L1100)
Deletion and Cleanup
Removing a workspace from the sidebar deletes its entry from the server registry but preserves the sessions and files on disk (for local workspaces). If the workspace was the currently active one, the system automatically navigates the user back to the default session route.
Sources: [apps/server/src/server.ts:880-911](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L880-L911), [apps/app/src/react-app/shell/session-route.tsx:1321-1341](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/app/src/react-app/shell/session-route.tsx#L1321-L1341)
Authorized Folders
For local workspaces, the server manages "Authorized Folders" which allow the OpenCode engine to read and write files outside the primary workspace root. These are stored within the permission.external_directory block of the opencode.jsonc file.
Sources: [apps/server/src/server.ts:607-658](https://github.com/different-ai/openwork/blob/69145e96cb721137e2de5e34acdc9a87d490bf38/apps/server/src/server.ts#L607-L658)
Conclusion
Workspace Management serves as the foundational layer for agentic collaboration in OpenWork. By abstracting the complexities of filesystem initialization and remote worker discovery into a unified lifecycle, it allows users to focus on the task at hand rather than environment configuration. The system's emphasis on portability through import/export and safety through authorized roots ensures that agentic workflows remain both flexible and secure.