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

> Explore OpenWork configuration options for different-ai/openwork. Customize ports, providers, flags, and UI with ServerConfig, WorkspaceConfig, and runtime settings.

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

---

**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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts) defines core server behavior including HTTP ports, storage paths, and feature flags.

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

```typescript
// 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`](https://github.com/different-ai/openwork/blob/main/openwork-runtime-config.ts) file builds the central `OpenworkRuntimeConfig` object that drives both server and UI behavior.

```typescript
// 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`.

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

```bash
OPENWORK_DEV_PROFILE=my-feature pnpm dev

```

Or use the worktree helper:

```bash
pnpm dev:worktree

```

## Build and Package Configuration

Each package in the monorepo uses TSUP bundler configurations:

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

```yaml

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

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

```

Typical EE deployment via Helm:

```bash
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:**

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

```

**Disable providers temporarily:**

```bash
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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/config.ts) | Server startup options | `ServerConfig` |
| [`apps/server/src/types.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/types.ts) | Workspace persistence | `WorkspaceConfig`, `OpencodeConfigFile` |
| [`apps/server/src/openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/desktop/tsconfig.electron.json) | Electron build settings | Electron builder options |
| `.env.dev` | Development environment | Environment variables |
| [`packaging/helm/openwork-ee/templates/configmap.yaml`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/desktop/tsconfig.electron.json) and related configuration files.