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

> Master the configuration of different-ai/openwork with our comprehensive guide. Learn to set up server, workspace, and runtime configurations for local and cloud deployments efficiently.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-05

---

**To configure different-ai/openwork, you layer multiple configuration sources: server-level `ServerConfig` in [`apps/server/src/config.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts), workspace-level `WorkspaceConfig` in [`apps/server/src/types.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/types.ts), runtime `OpenworkRuntimeConfig` in [`apps/server/src/openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts)) — Core process settings loaded at startup
- **WorkspaceConfig** ([`apps/server/src/types.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/types.ts)) — Per-workspace persistence and provider bindings
- **OpenworkRuntimeConfig** ([`apps/server/src/openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

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

## Workspace Configuration: WorkspaceConfig

Each workspace in OpenWork has its own `WorkspaceConfig` defined in [`apps/server/src/types.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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:

```bash

# 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:

```bash
OPENWORK_DEV_PROFILE=my-feature pnpm dev

```

Or use the convenience script:

```bash
pnpm dev:worktree

```

## Desktop Client Configuration

The Electron desktop client has its own configuration layer in [`apps/desktop/tsconfig.electron.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packaging/helm/openwork-ee/templates/configmap.yaml).

The ConfigMap injects environment variables into the Kubernetes deployment:

```yaml

# 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:

```bash
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`](https://github.com/different-ai/openwork/blob/main/packages/ui/tsup.config.react.ts):

```typescript
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packaging/helm/openwork-ee/values.yaml) |

## Summary

- **ServerConfig** ([`apps/server/src/config.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts)) — Process-level settings requiring restart
- **WorkspaceConfig** ([`apps/server/src/types.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/types.ts)) — Per-workspace persistence location and provider bindings
- **OpenworkRuntimeConfig** ([`apps/server/src/openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts) is evaluated once when the server process starts in [`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/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.