How to Configure OpenWork Desktop Policies for Enterprise Deployment

OpenWork desktop policies are configured through the Den back-end in OpenWork Cloud, where administrators define boolean feature flags that the desktop client retrieves via the /v1/desktop-config endpoint and applies using the calculateEffectiveDesktopPolicy algorithm to control capabilities like custom providers and extension management across the organization.

OpenWork provides a centralized desktop-policy system that allows enterprise administrators to govern which features are available to team members after they authenticate with the Cloud control plane (Den). By configuring these policies in the web-based admin interface, organizations can enforce security standards, restrict access to external AI providers, and customize the user experience without modifying client code. This guide explains how to configure OpenWork desktop policies for enterprise deployment using the Den policy engine, database schema, and desktop client integration, based on the implementation in the different-ai/openwork repository.

Understanding the Policy Data Model

The policy system relies on a static catalog of boolean feature flags defined in TypeScript and persisted in Den's PostgreSQL database.

Policy Definitions

The source of truth for available policy flags resides in packages/types/src/den/desktop-policies.ts. This file exports desktopPolicyDefinitions, an array where each entry contains:

• id: The machine-readable flag identifier
• name: Human-readable label shown in the admin UI
• description: Detailed explanation of the feature
• userNotice: Message displayed to end users when the feature is disabled
• defaultValue: Boolean default for new organizations

Database Schema and Assignments

Policies are stored in two primary tables defined in ee/apps/den-db/src/schema/desktop-policies.ts:

• desktopPolicy: Stores the actual policy documents with their boolean configurations
• desktopPolicyMember: Links policies to specific users or teams, enabling targeted restrictions

Assignments follow an inheritance model. A default policy applies to the entire organization, while specific policies can override defaults for individual members or teams through rows in desktopPolicyMember.

How Den Calculates Effective Desktop Policies

When a desktop client requests its configuration, Den executes the calculateEffectiveDesktopPolicy function (approximately line 340 in desktop-policies.ts) to resolve the final set of enabled features. The algorithm implements "any-grant wins" semantics:

1. Empty state check: If no policies exist for the organization (orgPolicyCount === 0), return allDesktopPolicies(true), granting full access.
2. Baseline initialization: Start with allDesktopPolicies(false), disabling all features by default.
3. Default policy merge: Apply the organization's default policy using normalizeDefaultDesktopPolicyValue.
4. Member policy merge: Iterate through assigned policies via normalizeDesktopPolicyValue, applying each in sequence.
5. Boolean union: For every feature flag, if any policy in the chain sets it to true, the final value becomes true.

The result is a Required<DesktopPolicyValue> object that the desktop client consumes to configure its UI.

Desktop Client Integration and Configuration

The desktop client loads policies through the Den Desktop Config endpoint at /v1/desktop-config. The response conforms to desktopConfigSchema (defined in packages/types/src/den/desktop-policies.ts), which extends the base policy schema with optional branding fields (brandAppName, brandLogoUrl) and a connectEnabled flag.

On the client side, the normalizeDesktopConfig helper processes the raw response. The desktop application checks specific keys to conditionally render UI components:

if (!policy.allowManageExtensions) {
  // hide the Extensions panel
}

Policies refresh automatically when the client starts and on an hourly cadence, ensuring compliance without requiring manual updates.

Managing Policies via OpenWork Cloud

Administrators configure policies through the Cloud web interface at app.openworklabs.com, documented in packages/docs/cloud/share-with-your-team/desktop-policies.mdx:

1. Select your organization from the workspace selector.
2. Navigate to Desktop policies in the settings menu.
3. Create a new policy or edit the existing default policy.
4. Toggle feature flags such as "Custom providers" or "Multiple workspaces" to match enterprise requirements.
5. Optionally assign the policy to specific members or teams using the member selector.

When saved, Den updates the desktopPolicy table via the API routes defined in ee/apps/den-api/src/routes/org/desktop-policies.ts. Changes propagate to active desktop clients within one hour or immediately upon restart.

Policy-Driven User Experience

The desktop client reflects policy restrictions through two primary mechanisms:

• Conditional rendering: UI components check policy booleans and omit inaccessible features entirely. For example, the extensions management panel disappears when allowManageExtensions is false.
• User notices: When a disabled feature is accessed, the client displays the userNotice text from the policy definition, clarifying that the organization administrator imposed the restriction.

Enterprise Example: Disabling Custom Model Providers

To prevent employees from adding personal API keys (such as individual OpenAI accounts), administrators can restrict custom provider configuration:

1. Open Desktop policies in the OpenWork Cloud admin panel.
2. Locate the "Custom providers" toggle (corresponds to allowCustomProviders).
3. Set the value to off and save the policy.

The next time desktop clients fetch their configuration, allowCustomProviders returns false. The provider management UI reacts by disabling the "Add Provider" button and displaying the configured notice: "Your organization administrator has disabled adding custom providers."

Implementation detail (client-side React hook):

import { useDesktopPolicy } from '@/hooks/useDesktopPolicy';

function AddProviderButton() {
  const { policy } = useDesktopPolicy();
  const enabled = policy.allowCustomProviders;

  return (
    <button
      disabled={!enabled}
      title={!enabled ? policyDefinitions.allowCustomProviders.userNotice : undefined}
    >
      Add Provider
    </button>
  );
}

Advanced Features: Configuring Team Prompt Cards

Desktop policies can distribute standardized prompt templates to team members. The schema includes onboardingPrompts and onboardingPromptDescriptions fields that administrators populate in the policy editor.

Den resolves prompt configurations using selectEffectiveOnboardingPromptConfig (lines approximately 520-560 in desktop-policies.ts). When multiple policies assign prompts, the highest-priority policy wins, allowing enterprises to standardize onboarding experiences across departments while permitting exceptions for specialized teams.

Security and Audit Considerations

Policy enforcement occurs entirely within the desktop client; the application never attempts blocked actions (such as calling the MCP to download a disallowed extension). This client-side validation prevents circumvention through API manipulation.

Den logs all policy modifications through its standard audit trail, capturing which administrator changed specific flags and when. Compliance teams can review these logs to track configuration drift and verify adherence to enterprise security standards.

Summary

• OpenWork desktop policies are boolean feature flags defined in packages/types/src/den/desktop-policies.ts and stored in the desktopPolicy and desktopPolicyMember tables.
• The calculateEffectiveDesktopPolicy function merges default and member-specific policies using "any-grant wins" logic to produce the effective configuration.
• Clients retrieve policies via the /v1/desktop-config endpoint and enforce restrictions locally through conditional UI rendering and user notices.
• Administrators manage policies through the OpenWork Cloud UI at app.openworklabs.com, with changes propagating to clients on startup or hourly refresh.
• Advanced use cases include restricting custom AI providers and distributing standardized prompt cards to team members.

Frequently Asked Questions

How often do desktop clients refresh their policy configuration?

Desktop clients fetch the effective policy at startup and subsequently refresh the configuration every hour. Additionally, the client reloads policies immediately when the user manually triggers a settings refresh or restarts the application, ensuring policy changes propagate within a reasonable timeframe without requiring real-time polling.

Can different teams within the same organization have different desktop policies?

Yes. While every organization maintains a default policy that applies to all members, administrators can create additional policies and assign them to specific users or teams through the desktopPolicyMember table. When calculating the effective policy, Den merges the default policy with any member-specific assignments, allowing granular control over feature access by department or role.

What happens if an administrator disables a feature while a user is actively using it?

The policy change takes effect on the client's next refresh cycle (within one hour) or immediately upon application restart. The desktop client validates capabilities locally before executing actions; if a feature like custom provider management is disabled, the UI hides the relevant controls and prevents the underlying API calls, effectively blocking continued use of the restricted functionality.

Where are policy definitions stored if I need to audit available feature flags?

The complete catalog of policy definitions resides in packages/types/src/den/desktop-policies.ts within the desktopPolicyDefinitions export. This TypeScript file serves as the source of truth for available flags, their default values, and the user-facing notices displayed when features are restricted. Administrators can review this file in the repository to understand which capabilities can be governed before configuring policies in the Cloud UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}