Workspace Creation Policies vs Organization Policies in OpenWork: Key Differences Explained

Workspace creation policies are hard-coded runtime guards that block creation only in gateway mode, while organization policies are persistent, admin-configurable flags stored in the database that control feature availability across the entire organization.

OpenWork (from the different-ai/openwork repository) uses two distinct layers of access control to determine whether users can create new workspaces. Understanding the difference between workspace creation policies and organization policies helps developers diagnose permission issues and administrators configure the correct restrictions for their teams.

Core Architectural Differences

Workspace Creation Policy: Runtime Enforcement

The workspace creation policy is a runtime-only check that determines if the current application host permits workspace creation. This policy lives in apps/app/src/app/lib/workspace-creation-policy.ts and contains no database records or persistent configuration.

According to the OpenWork source code, the function canCreateWorkspaces() implements a simple boolean check:

// apps/app/src/app/lib/workspace-creation-policy.ts
export function canCreateWorkspaces(): boolean {
  return !isOpenworkGatewayRuntime();
}

When the app runs inside the OpenWork gateway runtime, this function returns false, disabling the "Create Workspace" button and blocking creation requests. For plain web or desktop builds, it returns true, allowing creation. This behavior is verified in apps/app/tests/gateway-workspace-creation.test.ts, which validates the three runtime scenarios (gateway, plain web, and desktop).

Organization Policy: Configurable Feature Flags

Organization policies (also referred to as desktop policies in the codebase) are persistent, organization-wide settings stored in the openwork_workspace_configs table (or the legacy .opencode/openwork.json file). These policies allow administrators to toggle Boolean flags that restrict features across the entire organization.

The policy schema is defined in packages/types/src/den/desktop-policies.ts, which includes the allowMultipleWorkspaces flag (defaulting to true). The effective policy is computed by calculateEffectiveDesktopPolicy(), which merges default policies, assigned policies, and overrides.

Unlike the hard-coded runtime check, organization policies are modified by admins via the Organization Settings UI or the API endpoint /v1/desktop-policies/....

How Each Policy Is Evaluated

Runtime Gateway Check

The workspace creation policy evaluation is instantaneous and deployment-dependent. If the application detects it is running as a gateway client via isOpenworkGatewayRuntime(), creation is impossible regardless of user permissions or organization settings. Switching from a gateway build to a desktop build automatically changes this policy.

Database-Driven Policy Calculation

Organization policies follow a merge hierarchy. The system calculates the effective policy by combining the organization's default policy with any specific assignments and overrides. The flag allowMultipleWorkspaces specifically controls whether the UI renders the creation button and whether the backend accepts POST requests to create new workspaces.

The configuration is accessed through apps/server/src/openwork-workspace-config-store.ts, which provides readOpenworkWorkspaceConfig() to retrieve the JSON configuration for a specific workspace.

Code Implementation Examples

Checking Workspace Creation Permissions at Runtime

To conditionally render UI elements based on the runtime environment:

import { canCreateWorkspaces } from "./workspace-creation-policy";

if (!canCreateWorkspaces()) {
  // UI disables the “Create Workspace” button
  showError("Workspace creation is disabled in the gateway runtime.");
}

Reading Organization Policy from the Database

To check if an organization allows multiple workspaces:

import { readOpenworkWorkspaceConfig } from "./openwork-workspace-config-store";

async function isWorkspaceCreationAllowed(config: ServerConfig, workspaceId: string) {
  const cfg = await readOpenworkWorkspaceConfig(config, workspaceId);
  // `allowMultipleWorkspaces` defaults to true if missing
  return cfg.allowMultipleWorkspaces ?? true;
}

Updating Organization Policy via API

Administrators can toggle the organization-wide setting programmatically:

await fetch(`${apiUrl}/v1/desktop-policies/${policyId}`, {
  method: "PATCH",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ allowMultipleWorkspaces: false })
});

When to Use Each Policy Layer

Use the workspace creation policy when deploying thin gateway clients that should only proxy existing workspaces without allowing local creation. This requires no database configuration and is enforced purely by the deployment artifact.

Use organization policies when administrators need granular control over feature availability. The allowMultipleWorkspaces flag is ideal for restricting team workspace quotas, disabling custom providers, or controlling access to alpha features across the entire organization.

Summary

• Workspace creation policies are hard-coded in apps/app/src/app/lib/workspace-creation-policy.ts and evaluated at runtime via canCreateWorkspaces(), blocking creation only in gateway mode.
• Organization policies are defined in packages/types/src/den/desktop-policies.ts, persisted in openwork_workspace_configs, and managed via calculateEffectiveDesktopPolicy().
• The gateway runtime check requires no administrative configuration, while organization policies are toggled through the Organization Settings UI or API.
• Both layers must allow creation for the "Create Workspace" button to appear and function.

Frequently Asked Questions

Why can't users create workspaces in my OpenWork gateway deployment?

The canCreateWorkspaces() function in apps/app/src/app/lib/workspace-creation-policy.ts returns false when isOpenworkGatewayRuntime() detects a gateway environment. This is intentional behavior to prevent workspace creation in thin client mode. To enable creation, deploy the desktop or plain web build instead of the gateway runtime.

How do I restrict the number of workspaces my team can create?

Set the allowMultipleWorkspaces Boolean flag to false in your organization policy. This flag is defined in packages/types/src/den/desktop-policies.ts and stored via apps/server/src/openwork-workspace-config-store.ts. Changes take effect immediately for all users in the organization and hide the creation button in the UI.

Can organization policies override the gateway runtime restriction?

No. The workspace creation policy evaluated by canCreateWorkspaces() acts as a hard gate. If the app runs in gateway mode, creation is blocked regardless of the allowMultipleWorkspaces setting or any other organization policy configuration. The runtime check takes precedence over database-stored flags.

Where are organization policies stored in the database?

Organization policies are persisted in the openwork_workspace_configs table (or historically in .opencode/openwork.json files). The apps/server/src/openwork-workspace-config-store.ts module handles read/write operations for these configurations, while packages/types/src/den/desktop-policies.ts defines the TypeScript schema for valid policy keys like allowMultipleWorkspaces.

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