# How to Find and Configure Agent Runtime Settings in OpenMAIC

> Discover how to find and configure agent runtime settings in OpenMAIC. Learn to manage server-side environment variables in .env files and access them via the agentRuntimeConfig object.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```dotenv

# 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/entry-tree-storage.ts)** and **[`lib/server/agent-runtime/runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```

The storage layer in **[`lib/server/agent-runtime/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/resolve-model.ts)):

```dotenv
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```dotenv
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:

```dotenv

# 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/runner.ts) implementation enforces these limits during session scheduling.

## Accessing Configuration Programmatically

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

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

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/config.ts) for configuration access, [`runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/runner.ts) for execution logic, [`store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/store.ts) for persistence, and [`entry-tree-storage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/entry-tree-storage.ts) and [`lib/server/agent-runtime/runner.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.