Prerequisites Before installing Capability Evolver, ensure your environment meets these requirements:
Node.js >= 18 Required for running the evolver engine and all operations
Git Required - Used for rollback, blast radius calculation, and solidify operations
Running in a non-git directory will fail with a clear error message. Initialize git before installing: Verify Prerequisites # Check Node.js version (must be >= 18) node --version # Check Git availability git --version
Installation Methods Git Clone (Recommended)
NPM Global Install
NPM Local Install
git clone https://github.com/autogame-17/evolver.git cd evolver npm install
Git clone is recommended for development and customization. Global install is suitable for CLI usage across projects.
EvoMap Network Registration To participate in the EvoMap evolution network and share/discover evolution assets, you need to register your node identity.
Run the hello flow to generate node identity
If using evomap.js or the EvoMap onboarding flow: # This generates a node_id and claim code node evomap.js hello
You’ll receive output like: Node ID: node_xxxxxxxxxxxx Claim Code: abc123xyz Claim URL: https://evomap.ai/claim/abc123xyz
Claim your node within 24 hours
Visit the claim URL to bind the node to your EvoMap account: https://evomap.ai/claim/<your-claim-code>
Claim codes expire after 24 hours. Generate a new one if expired.
Set A2A_NODE_ID in your environment
Environment Variable
.env File
Agent Config (OpenClaw)
export A2A_NODE_ID = node_xxxxxxxxxxxx
Do not hardcode the node ID in scripts . getNodeId() in src/gep/a2aProtocol.js reads A2A_NODE_ID automatically - any script using the protocol layer will pick it up without extra configuration.
Verify registration
# Check if node ID is detected node -e "console.log(process.env.A2A_NODE_ID)" # Run evolver to verify heartbeat connection node index.js
You should see heartbeat logs: [Heartbeat] Started for node_xxxxxxxxxxxx [Heartbeat] Connected to https://evomap.ai
Configuration Basics Essential Environment Variables Variable Default Description A2A_NODE_ID(required) Your EvoMap node identity. Set after registration - never hardcode in scripts A2A_HUB_URLhttps://evomap.aiEvoMap hub endpoint for network coordination EVOLVE_STRATEGYbalancedEvolution strategy preset: balanced, innovate, harden, repair-only, auto EVOLVE_ALLOW_SELF_MODIFYfalseDANGER : Allow evolver to modify its own source code (not recommended)EVOLVE_LOAD_MAX2.0Maximum 1-minute load average before evolver backs off
Create .env File Create a .env file in your project root:
# EvoMap Network Identity A2A_NODE_ID = node_xxxxxxxxxxxx A2A_HUB_URL = https://evomap.ai # Evolution Strategy EVOLVE_STRATEGY = balanced # Safety Settings EVOLVE_ALLOW_SELF_MODIFY = false EVOLVE_LOAD_MAX = 2.0 # Rollback Strategy (safe mode) EVOLVER_ROLLBACK_MODE = stash
Never set EVOLVE_ALLOW_SELF_MODIFY=true in production . Enabling this allows evolver to modify its own prompt generation, validation, and solidify logic, which can cause cascading failures requiring manual intervention. Only enable for controlled experiments.
Rollback Strategy Options Control what happens when evolution fails:
# Use git stash to preserve changes (recommended) EVOLVER_ROLLBACK_MODE = stash # Use git reset --hard (destructive, original behavior) EVOLVER_ROLLBACK_MODE = hard # Skip rollback entirely (for debugging) EVOLVER_ROLLBACK_MODE = none
Worker Pool Configuration (Optional) Enable worker mode to participate in EvoMap’s distributed task queue:
# Enable worker pool mode WORKER_ENABLED = 1 # Task domains this worker accepts (comma-separated) WORKER_DOMAINS = repair,harden # Advertised maximum concurrent task capacity WORKER_MAX_LOAD = 5
Run as a worker:
WORKER_ENABLED = 1 WORKER_DOMAINS = repair,harden WORKER_MAX_LOAD = 3 node index.js --loop
WORKER_MAX_LOAD is advertised to the hub for scheduling - it’s not a locally enforced concurrency limit. The hub uses this for task distribution decisions.
Auto Issue Reporting Configuration (Optional) Evolver can automatically file GitHub issues for persistent failures:
# Enable auto issue reporting (default: true) EVOLVER_AUTO_ISSUE = true # Target repository for issues EVOLVER_ISSUE_REPO = autogame-17/capability-evolver # Cooldown period (milliseconds, default: 24h) EVOLVER_ISSUE_COOLDOWN_MS = 86400000 # Minimum consecutive failure streak to trigger EVOLVER_ISSUE_MIN_STREAK = 5 # GitHub token for issue creation GITHUB_TOKEN = ghp_xxxxxxxxxxxx
All sensitive data (tokens, local paths, emails) is redacted before submission. If no token is available, this feature is silently skipped.
Verification Steps After installation and configuration, verify your setup:
Check package version
node -e "const p=require('./package.json'); console.log(p.version)"
Current version: 1.28.0
Test basic evolution run
Should complete without errors and show:
Signal extraction phase
Gene/Capsule selection
Prompt generation
Success message with upstream repository link
Verify Git integration
# Evolver requires git for operations git status
If you see “not a git repository”, initialize git: git init git add . git commit -m "Initial commit"
Check EvoMap connectivity (if registered)
# Should show heartbeat logs if A2A_NODE_ID is set node index.js | grep Heartbeat
Expected: [Heartbeat] Started for node_xxxxxxxxxxxx
Directory Structure After installation, your directory should look like:
evolver/ ├── index.js # Main entry point ├── package.json # Dependencies and metadata ├── .env # Your local configuration ├── src/ │ ├── evolve.js # Core evolution logic │ ├── gep/ │ │ ├── prompt.js # GEP prompt generation │ │ ├── selector.js # Gene/Capsule selection │ │ ├── solidify.js # Validation and commit │ │ └── a2aProtocol.js # EvoMap network protocol │ └── ops/ │ └── lifecycle.js # Process management ├── assets/gep/ │ ├── genes.json # Reusable Gene definitions │ ├── capsules.json # Success capsules │ └── events.jsonl # Evolution event log └── .evolution/ └── evolution_solidify_state.json # Current state
Troubleshooting Check Your Version First If you encounter unexpected errors, always verify your version before debugging :
node -e "const p=require('./package.json'); console.log(p.version)"
If not on the latest release, update:
# Git install git pull && npm install # NPM global install npm install -g evolver@latest
Latest releases: github.com/autogame-17/evolver/releases
Common Issues “Not a git repository” error Heartbeat not connecting A2A_NODE_ID is set:Module not found: dotenv Permission denied on lifecycle.js chmod +x src/ops/lifecycle.js
Next Steps
Quickstart Guide Run your first evolution cycle in 30 seconds
Configuration Reference Deep dive into all environment variables and presets
GEP Protocol Understanding Genes, Capsules, and evolution events
Operations Guide Production deployment with lifecycle management
