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

> Understand the key differences between OpenWork workspace creation policies and organization policies. Learn how hard-coded guards differ from configurable flags to manage feature availability effectively.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: deep-dive
- Published: 2026-08-06

---

**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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
// 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) and stored via [`apps/server/src/openwork-workspace-config-store.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.opencode/openwork.json) files). The [`apps/server/src/openwork-workspace-config-store.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/openwork-workspace-config-store.ts) module handles read/write operations for these configurations, while [`packages/types/src/den/desktop-policies.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/desktop-policies.ts) defines the TypeScript schema for valid policy keys like `allowMultipleWorkspaces`.