How to Find and Configure Agent Runtime Settings in OpenMAIC

OpenMAIC's agent runtime is configured through server-side environment variables defined in .env files and consumed via the agentRuntimeConfig object in lib/server/agent-runtime/config.ts.

The agent runtime in OpenMAIC is a server-only background service that powers durable chat-agent sessions. Understanding where to find and configure these agent runtime settings is essential for deploying reliable, production-ready agents. This guide walks through the two-layer configuration system based on the THU-MAIC/OpenMAIC source code.

Where Agent Runtime Settings Are Defined

Environment Variables in .env.example

Runtime behavior is primarily controlled through environment variables. The repository provides a complete reference in .env.example (lines 40-73), which documents all tunable parameters with their default values.

Key variables include:

Variable	Purpose	Required
OPENMAIC_AGENT_RUNTIME_ENABLED	Master switch to enable/disable the runtime	Yes
DATABASE_URL	PostgreSQL connection string	Yes (when runtime enabled)
MODEL_ROUTES	JSON mapping for the maic-agent-driver stage	Yes (when runtime enabled)
OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS	How often the runner scans for claimable sessions	No (default: 1000)
OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS	Heartbeat refresh interval	No (default: 2000)
OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS	Lease expiration timeout	No (default: 10000)
OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT	Parallel session limit per instance	No (default: 2)
OPENMAIC_AGENT_RUNTIME_MAX_ATTEMPTS	Maximum retry attempts	No (default: 5)

Typed Configuration: agentRuntimeConfig

Environment variables are parsed and validated in lib/server/agent-runtime/config.ts (lines 5-18). This file exports agentRuntimeConfig, which serves as the single source of truth for the runner and related modules.

From the source:

// lib/server/agent-runtime/config.ts
export const agentRuntimeConfig = {
  enabled: process.env.OPENMAIC_AGENT_RUNTIME_ENABLED === 'true',
  scanIntervalMs: parseInt(process.env.OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS ?? '1000', 10),
  heartbeatIntervalMs: parseInt(process.env.OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS ?? '2000', 10),
  leaseTtlMs: parseInt(process.env.OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS ?? '10000', 10),
  maxConcurrent: parseInt(process.env.OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT ?? '2', 10),
  maxAttempts: parseInt(process.env.OPENMAIC_AGENT_RUNTIME_MAX_ATTEMPTS ?? '5', 10),
};

This centralization ensures consistent defaults and type-safe access throughout the runtime system.

Essential Configuration: Enable the Runtime

Before any agent runtime settings take effect, you must enable the service and provide mandatory dependencies.

Step 1: Enable the Runtime Switch

Add to your .env file:

# lib/server/agent-runtime/config.ts reads this to set agentRuntimeConfig.enabled

OPENMAIC_AGENT_RUNTIME_ENABLED=true

When disabled, the runtime gate in lib/server/agent-runtime/entry-tree-storage.ts and lib/server/agent-runtime/runner.ts returns 404 for all /api/agent/* endpoints.

Step 2: Configure PostgreSQL

The runtime requires a PostgreSQL database for session persistence. Without DATABASE_URL, the runner aborts on startup:

DATABASE_URL=postgres://openmaic:password@postgres:5432/openmaic

The storage layer in lib/server/agent-runtime/store.ts uses this connection for durable agent state.

Step 3: Route the Driver Stage

The MODEL_ROUTES variable must map the mandatory maic-agent-driver stage to a concrete provider. Validated at server start (see lib/server/agent-runtime/resolve-model.ts):

MODEL_ROUTES='{"maic-agent-driver":{"model":"openai:gpt-4o","api":"openai-completions"}}'

Missing or invalid routing causes session start failures.

Tuning Operational Parameters

Once enabled, fine-tune performance through optional environment variables. These map directly to agentRuntimeConfig properties consumed by lib/server/agent-runtime/runner.ts.

Scan and Heartbeat Timing

Setting	Default	Effect
OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS	1000 ms	Frequency of polling for claimable sessions
OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS	2000 ms	How often active sessions refresh their lease
OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS	10000 ms	Threshold for considering a session orphaned

Example configuration for lower latency:

OPENMAIC_AGENT_RUNTIME_SCAN_INTERVAL_MS=500
OPENMAIC_AGENT_RUNTIME_HEARTBEAT_MS=1500
OPENMAIC_AGENT_RUNTIME_LEASE_TTL_MS=6000

Concurrency and Resilience Limits

Control resource usage and failure handling:

# Allow 4 parallel sessions per instance (default: 2)

OPENMAIC_AGENT_RUNTIME_MAX_CONCURRENT=4

# Reduce retry attempts for faster failure detection (default: 5)

OPENMAIC_AGENT_RUNTIME_MAX_ATTEMPTS=3

The runner.ts implementation enforces these limits during session scheduling.

Accessing Configuration Programmatically

For custom scripts, extensions, or debugging, import the typed config directly:

import { agentRuntimeConfig } from '@/lib/server/agent-runtime/config';

// Verify runtime status
console.log('Runtime enabled:', agentRuntimeConfig.enabled);

// Read operational parameters
console.log('Scan interval (ms):', agentRuntimeConfig.scanIntervalMs);
console.log('Heartbeat interval (ms):', agentRuntimeConfig.heartbeatIntervalMs);
console.log('Lease TTL (ms):', agentRuntimeConfig.leaseTtlMs);
console.log('Max concurrent:', agentRuntimeConfig.maxConcurrent);
console.log('Max attempts:', agentRuntimeConfig.maxAttempts);

This approach guarantees you're reading parsed, validated values with fallback defaults applied.

Manual Runner Startup for Debugging

To start the runner directly with explicit configuration:

import { startRunner } from '@/lib/server/agent-runtime/runner';
import { agentRuntimeConfig } from '@/lib/server/agent-runtime/config';

if (agentRuntimeConfig.enabled) {
  startRunner({
    scanIntervalMs: agentRuntimeConfig.scanIntervalMs,
    heartbeatMs: agentRuntimeConfig.heartbeatIntervalMs,
    leaseTtlMs: agentRuntimeConfig.leaseTtlMs,
    maxConcurrent: agentRuntimeConfig.maxConcurrent,
    maxAttempts: agentRuntimeConfig.maxAttempts,
  });
  console.log('Agent runtime runner started with config from agentRuntimeConfig');
}

This pattern respects the declarative environment-based settings while allowing programmatic control.

Summary

• Agent runtime settings in OpenMAIC live in two places: .env files (source of truth) and lib/server/agent-runtime/config.ts (typed accessor).
• Mandatory variables: OPENMAIC_AGENT_RUNTIME_ENABLED, DATABASE_URL, and MODEL_ROUTES—without these, the runtime cannot start.
• Tuning variables: OPENMAIC_AGENT_RUNTIME_* prefixes control scan intervals, heartbeats, leases, concurrency, and retry behavior.
• Key files: config.ts for configuration access, runner.ts for execution logic, store.ts for persistence, and entry-tree-storage.ts for API gating.

Frequently Asked Questions

What happens if I don't set OPENMAIC_AGENT_RUNTIME_ENABLED?

The runtime remains disabled. According to the source code in lib/server/agent-runtime/entry-tree-storage.ts and lib/server/agent-runtime/runner.ts, all /api/agent/* endpoints return 404 Not Found, and no background session processing occurs.

Can I change agent runtime settings without restarting the server?

No. The agentRuntimeConfig object reads environment variables at import time (server startup). Changes to .env require a server restart to take effect, as the configuration is not hot-reloaded in the current implementation.

Why does the runtime require PostgreSQL specifically?

The storage layer in lib/server/agent-runtime/store.ts implements durable session state using PostgreSQL features for row locking and transactional consistency. The lease-based concurrency control and heartbeat mechanisms rely on database-level operations that are currently PostgreSQL-specific.

Where can I find the complete list of all runtime variables?

Reference the Agent Runtime section of .env.example (lines 40-73) at https://github.com/THU-MAIC/OpenMAIC/blob/main/.env.example. This file is maintained alongside the source and always reflects the latest available configuration options.

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