OpenWork Runtime Configuration System: How Dynamic Settings Updates Work Without Restarts

The OpenWork runtime configuration system enables live configuration changes through a provider-based merging architecture, JSON Patch API, and file-watcher reload mechanism that updates in-memory settings without process restarts.

The OpenWork platform implements a sophisticated runtime configuration system designed for production environments where downtime is unacceptable. Rather than requiring server restarts for configuration changes, OpenWork's architecture supports dynamic updates through a centralized config store, structured provider patterns, and live-reload capabilities. This article examines the internal mechanics of how OpenWork handles dynamic settings updates based on the different-ai/openwork source code.

Centralized Config Store Architecture

At the heart of OpenWork's dynamic configuration lies a dedicated storage layer that separates persistent configuration from runtime access patterns.

The Runtime Config Store

The runtime-opencode-config-store.ts module serves as the single source of truth for all runtime settings. It interfaces with the OpenWork Config DB (runtime-db.ts) to retrieve a JSON configuration document, then transforms this raw data into a typed OpenWorkRuntimeConfig object consumed throughout the server.

// Load the current runtime config (used throughout the server)
import { getRuntimeConfig } from '@/apps/server/src/runtime-opencode-config-store';

const cfg = await getRuntimeConfig();   // → OpenWorkRuntimeConfig object

This abstraction ensures that application code interacts with strongly-typed configuration objects while the storage layer handles persistence concerns.

Provider-Based Configuration Merging

OpenWork organizes configuration through provider modules — each feature domain (authentication, cloud plugins, extensions) registers its own configuration slice. During server startup, runtime-opencode-config-store.ts executes a merge operation that combines:

• Built-in default values from each registered provider
• Override values persisted in the OpenWork Config DB

The merge logic produces the final runtime configuration used by the application. The correctness of this merging behavior is validated in runtime-provider-merge.test.ts, which exercises boundary conditions where provider defaults conflict with database overrides.

Live-Reload via PATCH Endpoint and File Watching

The dynamic capabilities of the OpenWork runtime configuration system depend on a coordinated dance between HTTP API, database persistence, and in-process reloading.

JSON Patch API for Configuration Changes

OpenWork exposes an HTTP PATCH endpoint at /runtime/config that accepts JSON Patch documents per RFC 6902. This standardized patch format allows granular, atomic modifications to nested configuration structures.

When a client submits a patch:

1. The endpoint validates and applies the patch to the current configuration
2. The modified configuration is written to the OpenWork Config DB
3. A reload trigger is activated by touching an internal fingerprint file (reload-fingerprint.ts)

File-Watcher Reload Mechanism

The reload-watcher.ts module monitors the fingerprint file for modification events. Upon detecting a change, it:

• Re-reads the configuration from runtime-db.ts
• Re-executes the provider merge process
• Replaces the cached in-memory configuration object
• Ensures subsequent calls to getRuntimeConfig() return updated values

This architecture avoids the complexity of message-passing between processes or threads — the filesystem itself serves as the coordination mechanism.

// Disable a provider at runtime
await fetch('/runtime/config', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json-patch+json' },
  body: JSON.stringify([
    { op: 'add', path: '/disabledProviders/0', value: 'cloudPlugins' }
  ])
});

// Update a nested setting (e.g., change the default workspace path)
await fetch('/runtime/config', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json-patch+json' },
  body: JSON.stringify([
    { op: 'replace', path: '/workspace/defaultPath', value: '/new/default/path' }
  ])
});

The end-to-end behavior of this reload flow is comprehensively tested in runtime-config-patch-reload.e2e.test.ts, which verifies that PATCH requests propagate through the entire stack to affect live server behavior.

Automatic Configuration Migrations

Production systems inevitably evolve their configuration schemas. OpenWork addresses this through automatic migration logic that executes before configuration loading.

When the server detects a configuration document with an outdated schema version, the migration system transforms the document to match the current OpenWorkRuntimeConfig structure. This process runs automatically against the OpenWork Config DB, ensuring backward compatibility without manual intervention.

The migration system is validated by runtime-config-migrate.e2e.test.ts, which tests upgrade paths across multiple schema versions.

Runtime Provider Disabling

A critical operational capability in the OpenWork runtime configuration system is the ability to disable providers without code changes.

The top-level disabledProviders array in the runtime configuration allows administrators to suppress specific feature domains at runtime. Before initializing any provider, the server checks this list and skips instantiation for disabled entries.

// Example runtime config structure with provider disabling
{
  "disabledProviders": ["cloudPlugins", "legacyAuth"],
  "workspace": { "defaultPath": "/var/openwork" },
  // ... additional provider configurations
}

This capability enables emergency response scenarios — such as disabling a malfunctioning cloud integration — through a single API call rather than deployment pipelines. The functionality is tested in runtime-config-disabled-providers.test.ts.

Key Implementation Files

File	Responsibility
dev/apps/server/src/openwork-runtime-config.ts	Defines the OpenWorkRuntimeConfig type and read/write helpers
dev/apps/server/src/runtime-opencode-config-store.ts	Merges provider defaults with database overrides; caches final config
dev/apps/server/src/runtime-db.ts	Key-value persistence layer for raw configuration JSON
dev/apps/server/src/reload-watcher.ts	Watches fingerprint file and triggers in-process config regeneration
dev/apps/server/src/runtime-config-patch-reload.e2e.test.ts	End-to-end verification of PATCH-to-reload pipeline
dev/apps/server/src/runtime-config-migrate.e2e.test.ts	Schema migration testing across version transitions
dev/apps/server/src/runtime-config-disabled-providers.test.ts	Provider suppression behavior validation

Summary

• Centralized storage: The runtime-opencode-config-store.ts module provides typed access to configuration backed by runtime-db.ts persistence
• Provider architecture: Feature domains contribute configuration slices that merge together during load
• JSON Patch API: The /runtime/config PATCH endpoint accepts RFC 6902 patches for granular updates
• File-based reloading: reload-watcher.ts detects fingerprint changes and rebuilds in-memory configuration without process restart
• Schema evolution: Automatic migrations handle configuration format changes across versions
• Operational control: The disabledProviders array enables runtime feature toggling without deployments

Frequently Asked Questions

How does OpenWork apply configuration changes without restarting the server?

OpenWork uses a file-watcher pattern where configuration updates touch a fingerprint file (reload-fingerprint.ts), which reload-watcher.ts detects. This triggers a re-read from the database and reconstruction of the in-memory configuration object, making new settings available to subsequent requests while the process continues running.

What format does the OpenWork runtime configuration API accept?

The PATCH endpoint at /runtime/config requires JSON Patch documents (RFC 6902) with Content-Type: application/json-patch+json. This standard supports operations like add, remove, replace, move, copy, and test against JSON paths, enabling precise modifications without transmitting complete configuration documents.

Can OpenWork disable features dynamically without code deployment?

Yes. The disabledProviders array in the runtime configuration allows administrators to suppress specific providers through API calls. The server checks this list during provider initialization, preventing instantiation of disabled features without requiring code changes or restarts.

Where is configuration persisted in the OpenWork runtime system?

Runtime configuration is stored in the OpenWork Config DB via runtime-db.ts, which implements a lightweight key-value persistence layer. This database operates independently from application databases, ensuring configuration availability even during partial system failures.

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