The Role of openwork-runtime-config.ts in the OpenWork Agent Definition Lifecycle

The openwork-runtime-config.ts module serves as the central configuration hub that builds, persists, and synchronizes the runtime OpenCode configuration, bridging the runtime database and the OpenCode engine to ensure the agent definition remains live throughout the application lifecycle.

In the different-ai/openwork repository, the agent definition lifecycle relies on a deterministic configuration pipeline that transforms database state into engine-readable instructions. The openwork-runtime-config.ts file orchestrates this process by generating the single source of truth that defines the OpenWork agent's behavior, plugins, and provider settings.

Building the Runtime Configuration

The primary responsibility of apps/server/src/openwork-runtime-config.ts is assembling the engine-visible configuration from the runtime database. The buildOpenworkRuntimeConfig and buildOpenworkRuntimeConfigObject functions collect MCPs, plugins, providers, and the OpenWork agent definition into a deterministic JSON structure.

This configuration object is stable-stringified and written to runtime-opencode-config.json, which serves as the only configuration source the OpenCode engine reads during instance rebuilds. By centralizing this logic, the module ensures that every engine instance receives an identical, predictable definition of the agent's capabilities.

Defining the Agent Behavior

Within the generated configuration, the agent.openwork entry contains the OpenWork default agent definition. According to the source code at lines 33-53, this entry specifies:

• Description and mode parameters
• Temperature settings for the language model
• The complete OPENWORK_AGENT_PROMPT that drives the agent's behavioral logic

This embedded prompt and parameter set defines how the agent interprets requests and executes tasks, making openwork-runtime-config.ts the authoritative source for runtime agent personality and capabilities.

Synchronizing Dynamic Updates

The module implements a reactive update mechanism to keep the agent definition current without requiring server restarts. When the runtime database modifies—such as adding a new MCP, enabling a plugin, or disabling a provider—the server invokes writeOpenworkRuntimeConfigFile.

The keepOpenworkRuntimeConfigFileFresh function registers a persistent listener (onRuntimeOpencodeConfigWrite) that triggers on every database write. As implemented at lines 129-138, this guarantees that runtime-opencode-config.json is rewritten immediately upon any state change, ensuring the engine always sees the latest agent definition.

Integrating with the OpenCode Engine

The configuration file bridges persistent storage and transient engine instances. The server spawns or respawns the OpenCode engine with the environment variable OPENCODE_CONFIG pointing to runtime-opencode-config.json. Because the engine re-reads this file on each rebuild, modifications to the runtime database propagate instantly to new engine instances.

In apps/server/src/embedded.ts, the startup flow demonstrates this integration: writeOpenworkRuntimeConfigFile creates the initial configuration, then config.opencodeBaseUrl connects the managed OpenCode process to the freshly written settings.

Implementation Code Examples

Generating the runtime configuration

import { buildOpenworkRuntimeConfig } from "./openwork-runtime-config.js";

const json = await buildOpenworkRuntimeConfig(config, workspaceId);
// json → stable-stringified representation of the agent, plugins, MCPs, etc.

Persisting configuration changes

import { writeOpenworkRuntimeConfigFile } from "./openwork-runtime-config.js";

await writeOpenworkRuntimeConfigFile(config, workspaceId);
// → creates/updates runtime-opencode-config.json on disk

Enabling automatic synchronization

import { keepOpenworkRuntimeConfigFileFresh } from "./openwork-runtime-config.js";

const stop = keepOpenworkRuntimeConfigFileFresh(config, workspaceId);
// `stop()` unregisters the listener during server shutdown

Server startup integration

// In apps/server/src/embedded.ts
await writeOpenworkRuntimeConfigFile(config, workspace.id);   // ← creates the file
config.opencodeBaseUrl = managedOpencode.url;                // ← engine sees OPENCODE_CONFIG

Related Infrastructure

Several files collaborate to implement the complete agent definition lifecycle:

• apps/server/src/runtime-opencode-config-store.ts – Provides low-level read/write helpers (runtimeMcpMap, runtimeProviderMap) consumed by the main configuration builder.
• apps/server/src/server.ts – Imports writeOpenworkRuntimeConfigFile to trigger configuration updates when HTTP routes modify the runtime database.
• apps/server/src/embedded.ts – Demonstrates the startup flow where the configuration file is written and passed to the managed OpenCode engine.

Summary

• openwork-runtime-config.ts acts as the single source of truth for the OpenCode engine's view of the OpenWork agent.
• The buildOpenworkRuntimeConfig family of functions assembles deterministic JSON from the runtime database, including the agent.openwork definition with its prompt and parameters.
• writeOpenworkRuntimeConfigFile persists this state to runtime-opencode-config.json, while keepOpenworkRuntimeConfigFileFresh ensures immediate synchronization when the database changes.
• The OpenCode engine reads this file via the OPENCODE_CONFIG environment variable, allowing dynamic agent updates without server restarts.

Frequently Asked Questions

What triggers an update to the runtime configuration file?

Any modification to the runtime database triggers an update. The keepOpenworkRuntimeConfigFileFresh function registers a listener that calls writeOpenworkRuntimeConfigFile immediately after database writes, ensuring the runtime-opencode-config.json file always reflects the current state of MCPs, plugins, and provider settings.

How does the OpenCode engine access the agent definition?

The engine accesses the agent definition through the OPENCODE_CONFIG environment variable, which points to the runtime-opencode-config.json file generated by openwork-runtime-config.ts. The engine re-reads this file on every instance rebuild, allowing it to pick up configuration changes dynamically.

What determines the OpenWork agent's personality and capabilities?

The agent.openwork entry within the generated configuration determines these attributes. This entry includes the description, mode, temperature, and the full OPENWORK_AGENT_PROMPT that defines the agent's behavioral logic, as specified in lines 33-53 of openwork-runtime-config.ts.

Why is the runtime configuration considered deterministic?

The configuration is deterministic because buildOpenworkRuntimeConfigObject produces a stable-stringified JSON representation of the database state. This ensures that every engine instance receives an identical configuration for the same database state, preventing inconsistencies across multiple OpenCode engine rebuilds.

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