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

> Discover the critical role of openwork-runtime-config.ts in managing OpenWork agent definitions. Learn how it builds, persists, and synchronizes runtime configurations throughout the application lifecycle.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: internals
- Published: 2026-08-22

---

**The [`openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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

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

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

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

```

### Enabling automatic synchronization

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

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

```

### Server startup integration

```typescript
// 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts)** – Imports `writeOpenworkRuntimeConfigFile` to trigger configuration updates when HTTP routes modify the runtime database.
- **[`apps/server/src/embedded.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/runtime-opencode-config.json) file generated by [`openwork-runtime-config.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.