How to Configure different-ai/openwork: Complete Configuration Guide for Local and Cloud Deployments

To configure different-ai/openwork, you layer multiple configuration sources: server-level ServerConfig in apps/server/src/config.ts, workspace-level WorkspaceConfig in apps/server/src/types.ts, runtime OpenworkRuntimeConfig in apps/server/src/openwork-runtime-config.ts, environment variables in .env.dev, and Helm ConfigMaps for enterprise Kubernetes deployments.

OpenWork is a modular, locally-run desktop application with an optional cloud control-plane called OpenWork Den. Its configuration system is designed for flexibility—allowing you to control everything from HTTP ports and feature flags to provider credentials and UI behavior through layered, runtime-updatable settings. This guide breaks down each configuration source, how they interact, and how to modify them.

Configuration Architecture Overview

OpenWork uses a layered configuration model where settings cascade from hardcoded defaults through environment variables, workspace files, and finally runtime API updates. Understanding this hierarchy helps you choose the right place to make changes.

The four primary layers are:

• ServerConfig (apps/server/src/config.ts) — Core process settings loaded at startup
• WorkspaceConfig (apps/server/src/types.ts) — Per-workspace persistence and provider bindings
• OpenworkRuntimeConfig (apps/server/src/openwork-runtime-config.ts) — Live, dynamically updatable configuration served to the UI
• Environment variables (.env.dev, .env.example) — Development profiles and deployment secrets

Server-Level Configuration: ServerConfig

The foundation of OpenWork configuration is the ServerConfig interface defined in apps/server/src/config.ts. This controls process-level behavior that requires a restart to change.

Key settings include:

• HTTP server ports and workspace storage paths
• Feature flags such as enableMcp (Model Context Protocol) and allowRemoteDebug
• Authentication provider configurations

To modify server configuration, edit the TypeScript file directly:

// apps/server/src/config.ts
export interface ServerConfig {
  port: number;
  workspaceStoragePath: string;
  enableMcp: boolean;
  allowRemoteDebug: boolean;
  // ... additional fields
}

Note: Changes to ServerConfig require restarting the server process (apps/server/src/server.ts).

Workspace Configuration: WorkspaceConfig

Each workspace in OpenWork has its own WorkspaceConfig defined in apps/server/src/types.ts. This determines:

• Where the runtime configuration file is stored within the workspace directory
• Which providers are enabled or disabled for that specific workspace
• Migration behavior when workspace formats change

The workspace configuration typically lives at .openwork/workspace-config.json inside each workspace root, though the exact path is configurable per WorkspaceConfig.

Runtime Configuration: OpenworkRuntimeConfig

The most frequently modified configuration layer is OpenworkRuntimeConfig, built in apps/server/src/openwork-runtime-config.ts. This object merges:

1. Default values from the codebase
2. Workspace-level overrides from disk
3. Environment-derived flags (e.g., OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN)

The resulting configuration is:

• Written to disk at .openwork/runtime-config.json
• Served via GET /api/runtime-config
• Dynamically updatable via PATCH endpoints without server restart

Available Runtime Configuration Properties

Property	Description	Example
providers	Cloud AI provider credentials and settings	openai, anthropic, ollama
orgMode	Organization/team settings	enabled, teamId
denWebUrl	URL for OpenWork Den web interface	https://den.openwork.dev
openworkWebUrl	URL for OpenWork web client	https://app.openwork.dev
disabledProviders	List of provider IDs to hide from UI	["anthropic", "ollama"]

Dynamic Runtime Updates

You can modify runtime configuration without restarting the server using HTTP PATCH requests:

# Add or update a provider

curl -X PATCH http://localhost:8080/api/runtime-config/providers \
  -H "Content-Type: application/json" \
  -d '{"openai":{"apiKey":"sk-...","model":"gpt-4"}}'

# Disable specific providers

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

Environment Variables and Development Profiles

OpenWork uses .env.dev and .env.example files for environment-based configuration. These control development workflows and optional features.

Key Environment Variables

Variable	Purpose	Example
OPENWORK_DEV_PROFILE	Selects development configuration profile	my-feature, local-ai
PORT	HTTP server port	8080
OPENWORK_ELECTRON_REMOTE_DEBUG_PORT	Electron remote debugging port	9223
OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN	Uses mock keychain instead of OS keychain	true

To start OpenWork with a custom profile:

OPENWORK_DEV_PROFILE=my-feature pnpm dev

Or use the convenience script:

pnpm dev:worktree

Desktop Client Configuration

The Electron desktop client has its own configuration layer in apps/desktop/tsconfig.electron.json and related electron-builder configuration files.

Key settings include:

• Electron version and native module bindings
• OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN flag for CI/testing environments
• Remote debug port for development

These are typically set via environment variables rather than direct file edits.

Enterprise Kubernetes Configuration (EE)

For OpenWork Den enterprise deployments, configuration is managed through Helm in packaging/helm/openwork-ee/templates/configmap.yaml.

The ConfigMap injects environment variables into the Kubernetes deployment:

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: openwork-ee-config
data:
  OPENWORK_EE_LICENSE_KEY: "{{ .Values.licenseKey }}"
  # Additional EE-specific environment variables

Apply configuration changes with:

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

Package-Level Build Configuration

Each package in the monorepo has its own tsup.config.* files controlling TypeScript bundling. These affect how code is compiled but not runtime behavior.

Example from packages/ui/tsup.config.react.ts:

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  // Package-specific build options
});

Client-Side Configuration Cache

Both the web UI (ee/apps/den-web) and desktop UI consume runtime configuration through a client-side cache in ee/apps/den-web/app/(den)/_lib/runtime-config.ts.

This module:

1. Fetches /api/runtime-config on application load
2. Caches the result for subsequent renders
3. Determines which settings pages to display based on available providers and feature flags

The UI automatically re-renders when the runtime configuration changes, reflecting dynamic updates made via the PATCH API.

Typical Configuration Workflows

Goal	Method	Command/File
Change server port	Edit ServerConfig	apps/server/src/config.ts → restart
Enable MCP feature	Toggle ServerConfig flag	enableMcp: true → restart
Add OpenAI API key	PATCH runtime config	curl -X PATCH /api/runtime-config/providers
Disable Ollama provider	PATCH disabled providers	curl -X PATCH /api/runtime-config/disabled-providers -d '["ollama"]'
Use mock keychain in CI	Set environment variable	OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=true pnpm dev
Deploy EE with license	Configure Helm values	packaging/helm/openwork-ee/values.yaml

Summary

• ServerConfig (apps/server/src/config.ts) — Process-level settings requiring restart
• WorkspaceConfig (apps/server/src/types.ts) — Per-workspace persistence location and provider bindings
• OpenworkRuntimeConfig (apps/server/src/openwork-runtime-config.ts) — Dynamically updatable configuration served to UIs via /api/runtime-config
• Environment variables (.env.dev) — Development profiles, ports, and feature secrets
• Helm ConfigMap (packaging/helm/openwork-ee/templates/configmap.yaml) — Enterprise Kubernetes deployment settings
• PATCH endpoints — Runtime updates to providers and disabled-providers without restart

Frequently Asked Questions

What is the fastest way to add a new AI provider to OpenWork?

Use the PATCH /api/runtime-config/providers endpoint. This updates the live configuration immediately without requiring server restart. The provider appears in the UI as soon as the configuration is saved. For persistent changes across restarts, ensure the workspace's .openwork/runtime-config.json is writable.

How do I enable remote debugging in the OpenWork desktop client?

Set the OPENWORK_ELECTRON_REMOTE_DEBUG_PORT environment variable before starting the dev server, or add it to .env.dev. The desktop client will listen on the specified port for Chrome DevTools connections. For CI environments, also set OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=true to avoid OS keychain prompts.

Why do my ServerConfig changes not take effect immediately?

ServerConfig in apps/server/src/config.ts is evaluated once when the server process starts in apps/server/src/server.ts. Unlike runtime configuration, these settings are not hot-reloaded. Stop the server process completely and restart it for changes to apply.

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