# Evolver Environment Variables: Complete Guide to Core Settings and Timeouts

> Master Evolver environment variables for core settings and timeouts. Configure network, evolution, self-PR limits, and cleanup intervals with this comprehensive guide.

- Repository: [EvoMap/evolver](https://github.com/EvoMap/evolver)
- Tags: how-to-guide
- Published: 2026-04-17

---

**Evolver reads runtime configuration from environment variables defined in [`src/config.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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

```javascript
// 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:**

```bash
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:**

```dotenv

# .env

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

```

**Programmatic access:**

```javascript
// 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)](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)](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)](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)](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)](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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/src/config.js), they are consumed by specific modules: [`src/gep/selfPR.js`](https://github.com/EvoMap/evolver/blob/main/src/gep/selfPR.js) uses self-PR timeouts, [`src/atp/serviceHelper.js`](https://github.com/EvoMap/evolver/blob/main/src/atp/serviceHelper.js) applies HTTP transport timeouts, and [`src/gep/paths.js`](https://github.com/EvoMap/evolver/blob/main/src/gep/paths.js) resolves directory locations from path-related variables. This centralized import pattern ensures consistent defaults across the entire application.