Settings & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
- apps/app/src/react-app/domains/settings/shell/settings-shell.tsx
- apps/app/src/react-app/domains/settings/pages/debug-view.tsx
- apps/app/src/react-app/domains/settings/pages/shell-view.tsx
- apps/app/src/react-app/domains/settings/pages/mcp-view.tsx
- apps/app/src/react-app/domains/settings/pages/advanced-view-sections.tsx
- ee/apps/den-web/app/(den)/dashboard/_components/org-settings-screen.tsx/dashboard/_components/org-settings-screen.tsx)
- apps/app/src/react-app/domains/settings/computer-use-config.tsx
The Settings and Configuration system in OpenWork provides a comprehensive interface for managing application behavior, workspace-specific environments, extensions, and organizational policies. It is designed with a local-first philosophy while maintaining cloud readiness, allowing users to configure local services like OpenCode and OpenWork Server alongside remote cloud workers.
The system is partitioned into global settings (affecting the entire application), workspace settings (specific to a project folder), and organization settings (managed via OpenWork Cloud). This ensures that while individual users have control over their local environment, enterprises can enforce security and versioning policies across their teams.
Sources: AGENTS.md:14-25, apps/app/src/react-app/domains/settings/shell/settings-shell.tsx:210-215
Architecture and Navigation
The settings interface uses a shell-based architecture that can adapt between a standard sidebar-driven layout and a compact view. Navigation is organized into four primary groups: General, Workspace, Global, and Cloud.
Settings UI Structure
The UI utilizes a SettingsSidebar for primary navigation and a SidebarInset for content. In compact mode, it switches to a SettingsSectionMenu using dropdown triggers.
The diagram shows the hierarchical structure of the settings navigation, moving from the top-level shell to specific functional groups.
Sources: apps/app/src/react-app/domains/settings/shell/settings-shell.tsx:43-160
Workspace Configuration
Workspace configuration allows users to manage local folders, default models, and project-specific extensions.
Extension & MCP Management
The McpView handles the registration and status of Model Context Protocol (MCP) servers and OpenCode skills. It distinguishes between "Project" and "Global" configuration scopes, allowing extensions to be restricted to specific workspaces.
| Component | Description | Source |
|---|---|---|
| Quick Connect | One-click activation for popular tools like Notion, Linear, and Stripe. | mcp-view.tsx:505-550 |
| Configured Servers | Lists active MCP connections with real-time status (Ready, Needs Sign-in, Offline). | mcp-view.tsx:590-620 |
| Advanced Config | Provides direct access to opencode.json configuration files for manual editing. | mcp-view.tsx:805-820 |
Computer Use Configuration (macOS)
A specialized configuration module exists for "Computer Use" capabilities, which requires specific macOS permissions (Accessibility and Screen Recording) and a local MCP server connection.
This flow illustrates the interaction between the React UI, the Electron desktop bridge, and macOS system settings for security-sensitive features.
Sources: apps/app/src/react-app/domains/settings/computer-use-config.tsx:88-140
Advanced Diagnostics & Services
The Advanced and Debug views provide low-level control over the OpenWork runtime services. This is critical for developers to inspect the health of the underlying sidecar processes.
Runtime Services
OpenWork relies on two primary local services that can be managed through the settings:
- OpenCode Engine: The local runtime for agents and tool providers.
- OpenWork Server: The Bun-based local server hosting approvals and project audits.
Service Control Table
| Service | Action | Description | Source |
|---|---|---|---|
| OpenCode | Restart | Reboots the engine to apply binary or path changes. | debug-view.tsx:180-210 |
| OpenWork Server | Restart | Refreshes the API surface and audit logging. | debug-view.tsx:165-179 |
| Sandbox | Probe | Runs a temporary Docker startup check to verify sandbox availability. | debug-view.tsx:425-450 |
Sources: apps/app/src/react-app/domains/settings/pages/debug-view.tsx:160-230, apps/app/src/react-app/domains/settings/pages/advanced-view-sections.tsx:75-95
Organization & Cloud Settings
Enterprise features are managed through the Organization Settings screen, which allows administrators to control access and security policies.
Core Policies
- Domain Restrictions: Admins can allow join requests only from specific email domains.
- SSO Requirement: Forces members to use the workspace's configured SAML/SSO provider.
- Version Control: Allows admins to specify a list of "Allowed Desktop Versions" that are permitted to connect to the organization's server.
This diagram outlines the administrative flow for updating organization-wide security and versioning policies.
Sources: ee/apps/den-web/app/(den)/dashboard/_components/org-settings-screen.tsx:110-180, ee/apps/den-web/app/(den)/dashboard/_components/org-settings-screen.tsx:390-450
Shell Customization
The ShellCustomizationView provides a wireframe-based interface for toggling UI components. This allows users to hide distractions or enable specific power-user features.
Configurable Layout Elements
- Sidebar & Status Bar: Visibility toggles for main navigation and bottom status regions.
- Task Suggestions: Toggles the "Starter Cards" seen on new session pages.
- Branding: Allows changing the application name (Note: some branding features are Cloud-managed/locked).
- Environment Variables: A dedicated section for managing local API keys used by agents (e.g.,
ANTHROPIC_API_KEY).
Sources: apps/app/src/react-app/domains/settings/pages/shell-view.tsx:190-260, apps/app/src/i18n/locales/en.ts:settings.environment.title
Summary
Settings & Configuration in OpenWork serves as the central control plane for both the local runtime and cloud-connected enterprise environments. It bridges the gap between low-level process management (OpenCode/OpenWork Server) and high-level organizational policy (SSO/Domain restrictions), providing a scalable interface that supports both solo developers and large teams. Key functionality includes extension management via MCP, macOS permission handling for advanced agent capabilities, and detailed diagnostic reporting for troubleshooting.