OpenWork Configuration Options: Complete Guide for different-ai/openwork Setup

OpenWork configuration options include layered ServerConfig, WorkspaceConfig, and OpenworkRuntimeConfig interfaces that control HTTP ports, provider settings, feature flags, and UI behavior through TypeScript files in apps/server/src/ and environment variables.

OpenWork is a modular, locally-run desktop application with an optional cloud control-plane (OpenWork Den). Understanding the configuration architecture is essential for customizing both development and production deployments of the different-ai/openwork repository.

Core Configuration Files and Interfaces

The configuration system in different-ai/openwork uses TypeScript interfaces defined across several key files. Each interface serves a distinct purpose in the configuration hierarchy.

ServerConfig: Application-Level Settings

The ServerConfig interface in apps/server/src/config.ts defines core server behavior including HTTP ports, storage paths, and feature flags.

// apps/server/src/config.ts
interface ServerConfig {
  port: number;
  workspaceStoragePath: string;
  enableMcp: boolean;
  allowRemoteDebug: boolean;
  authenticationProviders: string[];
}

Key ServerConfig options:

• port – HTTP server port (default varies by environment)
• workspaceStoragePath – Filesystem location for workspace data
• enableMcp – Toggle for Model Context Protocol support
• allowRemoteDebug – Enable remote debugging endpoints
• authenticationProviders – Configured auth backends (OAuth, etc.)

WorkspaceConfig: Per-Workspace Persistence

Each workspace maintains its own configuration through the WorkspaceConfig interface defined in apps/server/src/types.ts.

// apps/server/src/types.ts
interface WorkspaceConfig {
  runtimeConfigLocation: string;
  enabledProviders: string[];
  disabledProviders: string[];
  migrationBehavior: 'auto' | 'manual';
}

This interface controls:

• runtimeConfigLocation – Path to the workspace's runtime configuration JSON
• enabledProviders – Cloud AI providers active for this workspace
• disabledProviders – Explicitly disabled provider IDs
• migrationBehavior – How schema updates are handled

OpenworkRuntimeConfig: Live Runtime State

The openwork-runtime-config.ts file builds the central OpenworkRuntimeConfig object that drives both server and UI behavior.

// apps/server/src/openwork-runtime-config.ts
interface OpenworkRuntimeConfig {
  providers: Record<string, ProviderConfig>;
  orgMode: boolean;
  denWebUrl: string;
  openworkWebUrl: string;
  featureToggles: Record<string, boolean>;
}

This runtime configuration is:

1. Generated at server startup by merging defaults, workspace overrides, and environment flags
2. Written to disk as JSON
3. Served via the /api/runtime-config HTTP endpoint
4. Consumed by both web and desktop UIs

Client-Side Configuration Consumption

Den-Web UI Runtime Config

The enterprise web UI caches server configuration in ee/apps/den-web/app/(den)/_lib/runtime-config.ts.

// ee/apps/den-web/app/(den)/_lib/runtime-config.ts
// Fetches /api/runtime-config on mount, caches result for settings panel rendering

This client-side cache determines which configuration panels to render—Provider settings, OpenAI image generation, Ollama local models, etc.

Desktop Client Build Configuration

The Electron desktop client uses apps/desktop/tsconfig.electron.json and related files to configure:

• Electron version and native modules
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN flag for testing
• Remote debug port via OPENWORK_ELECTRON_REMOTE_DEBUG_PORT

Environment Variable Configuration

Development and runtime behavior can be controlled through .env.dev or .env.example files:

Variable	Purpose	Example
OPENWORK_DEV_PROFILE	Select development feature profile	my-feature
PORT	Override default HTTP port	8080
OPENWORK_ELECTRON_REMOTE_DEBUG_PORT	Enable Electron remote debugging	9223
OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN	Use mock credential storage	true

Start with a custom profile:

OPENWORK_DEV_PROFILE=my-feature pnpm dev

Or use the worktree helper:

pnpm dev:worktree

Build and Package Configuration

Each package in the monorepo uses TSUP bundler configurations:

// packages/ui/tsup.config.react.ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true
});

These tsup.config.* files across packages/*/ control entry points, output formats, and TypeScript declaration generation.

Enterprise Deployment Configuration

For Kubernetes deployments, packaging/helm/openwork-ee/templates/configmap.yaml injects environment variables:

# packaging/helm/openwork-ee/templates/configmap.yaml

apiVersion: v1
kind: ConfigMap
data:
  OPENWORK_EE_LICENSE_KEY: "{{ .Values.license.key }}"

Typical EE deployment via Helm:

helm upgrade openwork-ee ./packaging/helm/openwork-ee -f values.yaml

Runtime Configuration Updates

The different-ai/openwork server supports dynamic configuration changes without restart:

Add or update a provider:

curl -X PATCH /runtime-config/providers \
  -H "Content-Type: application/json" \
  -d '{"openai":{"apiKey":"sk-..."}}'

Disable providers temporarily:

curl -X PATCH /runtime-config/disabled-providers \
  -H "Content-Type: application/json" \
  -d '["anthropic","ollama"]'

File Reference Summary

Path	Configuration Role	Interface/Object
apps/server/src/config.ts	Server startup options	ServerConfig
apps/server/src/types.ts	Workspace persistence	WorkspaceConfig, OpencodeConfigFile
apps/server/src/openwork-runtime-config.ts	Runtime state generation	OpenworkRuntimeConfig
ee/apps/den-web/app/(den)/_lib/runtime-config.ts	UI configuration cache	Client-side runtime config
apps/desktop/tsconfig.electron.json	Electron build settings	Electron builder options
.env.dev	Development environment	Environment variables
packaging/helm/openwork-ee/templates/configmap.yaml	Kubernetes deployment	Helm ConfigMap
packages/*/tsup.config.*	Package bundling	TSUP configuration objects

Summary

• OpenWork configuration is layered: ServerConfig for global settings, WorkspaceConfig per workspace, and OpenworkRuntimeConfig for live UI-driven state.

• Three update mechanisms exist: Edit TypeScript source files and restart, modify workspace JSON directly, or use PATCH endpoints for runtime changes.

• Environment variables bridge layers: OPENWORK_DEV_PROFILE, port settings, and feature flags propagate from .env files through to the running server.

• Enterprise deployments use Helm: The configmap.yaml template maps configuration into container environment variables.

• UI behavior is configuration-driven: Both web and desktop clients fetch /api/runtime-config to determine which settings panels and providers to expose.

Frequently Asked Questions

How do I change the default HTTP port in OpenWork?

Set the PORT environment variable before starting the server, or modify the port field in apps/server/src/config.ts. For development, use PORT=8080 pnpm dev.

What is the difference between enabledProviders and disabledProviders in WorkspaceConfig?

enabledProviders lists explicitly configured provider IDs, while disabledProviders temporarily deactivates providers without removing their configuration. A provider in disabledProviders takes precedence—PATCH to /runtime-config/disabled-providers toggles availability without changing stored credentials.

Can I update OpenWork configuration without restarting the server?

Yes. The /runtime-config/providers and /runtime-config/disabled-providers endpoints accept PATCH requests for live updates. However, changes to ServerConfig fields like enableMcp or allowRemoteDebug require a server restart since they're read once at startup from apps/server/src/config.ts.

Where should I configure the OpenWork Electron desktop client?

Use OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN for testing without system keychain access, and OPENWORK_ELECTRON_REMOTE_DEBUG_PORT to attach Chrome DevTools. These are read from environment variables at build time via apps/desktop/tsconfig.electron.json and related configuration files.

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