Evolver Environment Variables: Complete Guide to Core Settings and Timeouts

Evolver reads runtime configuration from environment variables defined in src/config.js, covering network timeouts, evolution loops, self-PR limits, and cleanup intervals, with all values accessible via helper functions envInt, envFloat, and envStr.

The EvoMap/evolver repository uses a centralized configuration system that allows operators to tune agent behavior without modifying source code. By setting environment variables before launch, you control critical timeouts, validation thresholds, and automatic maintenance parameters that govern how the evolution engine interacts with the A2A hub and manages its own lifecycle.

Network and A2A Configuration

Evolver's communication with the A2A hub relies on timeout variables that control handshake duration, heartbeat frequency, and transport limits. These are parsed in src/config.js and consumed by the networking layer.

• EVOLVER_HELLO_TIMEOUT_MS – Timeout for the initial handshake with the hub (default: 15000 ms)
• EVOLVER_HEARTBEAT_TIMEOUT_MS – Maximum wait for heartbeat response (default: 10000 ms)
• HEARTBEAT_INTERVAL_MS – Frequency of heartbeat transmissions (default: 360000 ms)
• EVOLVER_HEARTBEAT_FIRST_DELAY_MS – Delay before first heartbeat post-startup (default: 30000 ms)
• EVOLVER_EVENT_POLL_TIMEOUT_MS – Maximum duration for event polling (default: 60000 ms)
• EVOLVER_HTTP_TRANSPORT_TIMEOUT_MS – Default HTTP request timeout for the ATP client (default: 15000 ms)
• EVOLVER_SECRET_CACHE_TTL_MS – TTL for cached secrets like LLM keys (default: 60000 ms)
• EVOLVER_HUB_SEARCH_TIMEOUT_MS – Timeout for hub-search API calls (default: 8000 ms)

Solidify and Validation Settings

The solidification pipeline and validation runner use environment variables to set execution limits and quality thresholds. These values determine how long validation can run and when a capsule is considered acceptable for publication.

• EVOLVER_VALIDATION_TIMEOUT_MS – Maximum time a validation run may take (default: 180000 ms)
• EVOLVER_CANARY_TIMEOUT_MS – Timeout for the canary (quick sanity) check (default: 30000 ms)
• EVOLVER_CAPSULE_MAX_CHARS – Maximum size of a capsule sent to the hub (default: 8000 chars)
• EVOLVER_SOLIDIFY_RETRY_INTERVAL_MS – Delay between solidify retry attempts (default: 1000 ms)
• EVOLVER_MIN_PUBLISH_SCORE – Minimum score before a capsule is published (default: 0.78)

Evolution Loop Parameters

The core evolution loop and memory management system expose variables that control archiving frequency, repair attempts, and prompt size limits.

• EVOLVER_REPAIR_LOOP_THRESHOLD – How many repair attempts before giving up (default: 3)
• EVOLVER_SESSION_ARCHIVE_TRIGGER – Number of sessions that trigger automatic archiving (default: 100)
• EVOLVER_SESSION_ARCHIVE_KEEP – How many archived sessions to retain (default: 50)
• EVOLVER_MEMORY_FRAGMENT_MAX_CHARS – Maximum size of a memory fragment (default: 50000 chars)
• EVOLVER_IDLE_FETCH_INTERVAL_MS – How often the idle fetcher runs (default: 600000 ms)
• EVOLVER_PROMPT_MAX_CHARS – Maximum size of a generated prompt (default: 24000 chars)

Operations and Cleanup Configuration

Maintenance routines use environment variables to determine when the agent is idle, how long to keep assets, and how aggressively to prune files.

• EVOLVER_MAX_SILENCE_MS – Maximum period of silence before the agent is considered idle (default: 1800000 ms)
• EVOLVER_CLEANUP_MAX_AGE_MS – Age after which old assets are removed (default: 86400000 ms)
• EVOLVER_CLEANUP_MIN_KEEP – Minimum number of items to keep during cleanup (default: 10)
• EVOLVER_CLEANUP_MAX_FILES – Maximum files to delete in one cleanup pass (default: 10)
• EVOLVER_LOCK_MAX_AGE_MS – TTL for lock files used to coordinate concurrent runs (default: 600000 ms)

Self-PR and Auto-Contribute Settings

The experimental self-PR feature that allows Evolver to propose its own code changes uses a dedicated set of environment variables to control quality thresholds and safety limits.

• EVOLVER_SELF_PR_MIN_SCORE – Minimum mutation score required to open a PR (default: 0.85)
• EVOLVER_SELF_PR_MIN_STREAK – Required streak of successful PRs before auto-merging (default: 3)
• EVOLVER_SELF_PR_MAX_FILES – Maximum files a self-PR may touch (default: 3)
• EVOLVER_SELF_PR_MAX_LINES – Maximum lines a self-PR may modify (default: 100)
• EVOLVER_SELF_PR_COOLDOWN_MS – Cooldown period after a self-PR is opened (default: 86400000 ms)
• EVOLVER_SELF_PR_REPO – Target repository for self-PRs (default: EvoMap/evolver)
• EVOLVER_SELF_PR_TIMEOUT_MS – Timeout for the whole self-PR workflow (default: 30000 ms)

Security and Proxy Integration

Additional variables handle secret scanning behavior and proxy configuration for hub communication.

• EVOLVER_LEAK_CHECK – Mode for the secret-leak detector (warn, error, or off; default: warn)
• EVOMAP_PROXY_PORT – Port for the local proxy server (default: undefined)
• A2A_HUB_URL / EVOMAP_HUB_URL – Base URL for the hub API (default: https://evomap.ai)
• A2A_NODE_SECRET / EVOMAP_NODE_SECRET – Shared secret for hub authentication (default: undefined)
• A2A_NODE_ID / EVOMAP_NODE_ID – Unique node identifier (default: undefined)
• A2A_MAX_FILES / A2A_MAX_LINES – Limits used by the A2A protocol when pulling code (defaults: 5 files, 200 lines)

Configuration Implementation

All environment variables are parsed through a unified helper layer in src/config.js. This ensures type safety and consistent defaults across the codebase.

The three helper functions used are:

• envInt(key, fallback) – Parses integer values with NaN protection
• envFloat(key, fallback) – Parses floating point thresholds
• envStr(key, fallback) – Returns raw string values

// src/config.js – helper implementation
function envInt(key, fallback) {
  const v = process.env[key];
  if (v === undefined || v === '') return fallback;
  const n = parseInt(v, 10);
  return isNaN(n) ? fallback : n;
}

Usage Examples

Configure Evolver via shell exports, .env files, or direct process environment manipulation.

Shell configuration:

export EVOLVER_HELLO_TIMEOUT_MS=20000
export EVOLVER_HTTP_TRANSPORT_TIMEOUT_MS=10000
export EVOLVER_SELF_PR_MAX_FILES=5
export A2A_HUB_URL="https://my-custom-hub.example.com"

node index.js

Environment file:

# .env

EVOLVER_HEARTBEAT_TIMEOUT_MS=15000
EVOLVER_SELF_PR_TIMEOUT_MS=45000
EVOLVER_LEAK_CHECK=error
EVOLVER_MIN_PUBLISH_SCORE=0.85

Programmatic access:

// Direct access (rarely needed)
const timeout = process.env.EVOLVER_SELF_PR_TIMEOUT_MS || 30000;

Key Implementation Files

File	Purpose
[src/config.js](https://github.com/EvoMap/evolver/blob/main/src/config.js)	Central definition of all core env-vars and defaults
[src/gep/paths.js](https://github.com/EvoMap/evolver/blob/main/src/gep/paths.js)	Uses EVOLVER_REPO_ROOT, EVOLVER_LOGS_DIR, EVOLVER_MEMORY_DIR for directory resolution
[src/gep/privacyClient.js](https://github.com/EvoMap/evolver/blob/main/src/gep/privacyClient.js)	Demonstrates PRIVACY_TIMEOUT_MS and hub URL overrides
[src/gep/selfPR.js](https://github.com/EvoMap/evolver/blob/main/src/gep/selfPR.js)	Implements the self-PR workflow with SELF_PR_TIMEOUT_MS
[src/atp/serviceHelper.js](https://github.com/EvoMap/evolver/blob/main/src/atp/serviceHelper.js)	Applies HTTP_TRANSPORT_TIMEOUT_MS to ATP client calls

Summary

• Evolver's entire runtime configuration is centralized in src/config.js and driven by environment variables with sensible defaults.
• Network and A2A variables control handshake, heartbeat, and transport timeouts ranging from 8 to 60 seconds.
• Solidification settings enforce quality gates through EVOLVER_MIN_PUBLISH_SCORE and size limits like EVOLVER_CAPSULE_MAX_CHARS.
• Evolution loop parameters manage memory fragmentation, session archiving, and repair thresholds.
• Self-PR configuration provides safety limits on autonomous code changes, including file count, line count, and cooldown periods.
• All values are parsed through type-safe helpers (envInt, envFloat, envStr) that fallback to defaults when variables are unset or invalid.

Frequently Asked Questions

How do I override the default timeout for hub connections?

Set EVOLVER_HELLO_TIMEOUT_MS and EVOLVER_HTTP_TRANSPORT_TIMEOUT_MS before starting the process. For example, export EVOLVER_HELLO_TIMEOUT_MS=20000 increases the initial handshake window to 20 seconds. These variables are read at startup by the envInt helper in src/config.js.

What is the difference between EVOLVER_SELF_PR_MAX_FILES and A2A_MAX_FILES?

EVOLVER_SELF_PR_MAX_FILES (default: 3) limits how many files Evolver may modify when generating an autonomous pull request. A2A_MAX_FILES (default: 5) restricts how many files the A2A protocol will pull from the hub during a code fetch operation. The former governs outbound contributions, while the latter governs inbound synchronization.

Can I disable the secret leak detector entirely?

Yes. Set EVOLVER_LEAK_CHECK=off to disable the secret-leak detector, or use error to force the process to exit when leaks are detected. The default value is warn, which logs suspicious patterns without stopping execution. This variable is parsed as a string via envStr in the configuration module.

Where are environment variables actually used in the codebase?

While all variables are defined in src/config.js, they are consumed by specific modules: src/gep/selfPR.js uses self-PR timeouts, src/atp/serviceHelper.js applies HTTP transport timeouts, and src/gep/paths.js resolves directory locations from path-related variables. This centralized import pattern ensures consistent defaults across the entire application.

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