Aether Forge

Spec-first agent builder framework. Idea to governed, testable, production-capable agent in one CLI.


# Install from GitHub (not yet on PyPI)
pip install 'aether-forge @ git+https://github.com/HeyElsa/aether-forge.git'
 
# Or clone and install locally for framework development
git clone https://github.com/HeyElsa/aether-forge.git
cd aether-forge
pip install -e '.[dev]'

Start with the First 10 Minutes path before adding wallets, x402 payments, or live trading. If you are not sure which guide fits your use case, use Choose Your Path.

What is Aether Forge?

Building autonomous agents today means scattered configs, no policy enforcement, untested deployments, and zero auditability. Moving to production is a leap of faith.

Aether Forge gives every agent a governed lifecycle: typed specs, policy-checked execution, scenario-driven evaluation, and evidence-backed promotion from sandbox to production.

Every tick, an LLM re-reads your plain-English strategy, picks from declared capabilities, and emits typed steps the runtime executes against four layers of memory.

Key Features

Feature	What it does
LLM-Driven	Auto-detect Claude, GPT, Gemini, OpenRouter, or local Ollama fallback. Any model, hot-swappable.
Real Wallets	OWS across 9 chain families with encrypted AES-256-GCM backups
A2A Protocol	Agent-to-agent task delegation via Google’s A2A (JSON-RPC over HTTP)
x402 Payments	Agents send AND receive USDC on Base mainnet via EIP-3009
MCP Tools	Consume any Model Context Protocol server — filesystem, GitHub, messaging
On-Chain ID	ERC-8004 Agent NFT on Base mainnet. 61,000+ agents in the registry
4-Layer Memory	Replays, working set, SQLite diary, MemPalace knowledge graph
Security	AES-256-GCM backups, prompt injection scanning, kill switch, 8-point audit
Autoresearch	Karpathy keep-or-discard loop for runtime strategy self-improvement

Quick Example


# Zero-risk first run: no API key, no wallet, no live funds
forge generate-fast \
  --name "hello-agent" \
  --idea "read an input, reason about it, and report a short summary" \
  --output ./hello-agent \
  --planner-mode heuristic
 
# Validate all artifacts
forge validate ./hello-agent
 
# Run one sandbox tick
forge run ./hello-agent --max-ticks 1 --interval 0 --environment sandbox --auto-approve

Crypto-native agents are available when you opt in:


forge generate-fast --name "ETH Watcher" --idea "monitor ETH markets" \
  --output ./eth-watcher --wallet --planner-mode heuristic
 
forge run ./eth-watcher --environment sandbox --mode paper --auto-approve

First-Run Map

Need	Page
A safe first run	First 10 Minutes
The right install command	Install Matrix
What generated files mean	Generated Agent Anatomy
A route by goal	Choose Your Path
Common failures	Troubleshooting

Architecture

Every agent action flows through the same governed pipeline:


Planner ──▶ Policy Gate ──▶ Execute ──▶ Step Ledger
   ^                                        │
   └──────── loop (max 20 steps) ───────────┘

Planner proposes next steps (LLM-driven by default)
Policy Gate evaluates rules: environment, notional limits, wallet chains, approvals
Execute runs the capability via the appropriate router
Ledger records every step for audit, replay, and resumption

Side-effecting capabilities default to deny until policy explicitly allows.