Skip to Content
DocumentationGetting Started

Getting Started

Get from a clean machine to a validated, running agent without an API key, wallet, or live funds.

Want the shortest possible path? Use First 10 Minutes. Need help choosing an install or feature guide? Use Choose Your Path.

Install

Note: Aether Forge is not yet published to PyPI. Until then, install directly from GitHub.

python3 -m venv .venv
source .venv/bin/activate
pip install 'aether-forge @ git+https://github.com/HeyElsa/aether-forge.git'

For local framework development:

git clone https://github.com/HeyElsa/aether-forge.git
cd aether-forge
pip install -e '.[dev]'

Requires Python 3.12+. The core install has one runtime dependency: jsonschema.

Verify the Runtime

forge doctor

Expected shape:

[  ok] Python version: Python 3.12+
[  ok] jsonschema: jsonschema ...
[  ok] Memory store (SQLite): Layer 3 round-trip ok (write + read)

Healthy (with optional skips) — ...

Skipped wallet, knowledge, or security checks are fine for the first run. They are optional extras.

Generate a Zero-Risk Agent

This first agent uses the offline heuristic planner. It does not call an LLM, create a wallet, move money, or require provider credentials.

forge generate-fast \
  --name "hello-agent" \
  --idea "read an input, reason about it, and report a short summary" \
  --output ./hello-agent \
  --planner-mode heuristic

This creates a complete agent directory:

hello-agent/
  aether-forge.json
  agent-spec.json
  capability-manifest.json
  policy-bundle.json
  scenario-pack.json
  scaffold.manifest.json
  Dockerfile
  Makefile
  tests/test_agent.py

Validate and Evaluate

forge validate ./hello-agent
forge eval-pack ./hello-agent

The generated agent also ships day-one developer targets:

cd ./hello-agent
make test
make eval-pack
make doctor

Run One Tick

forge run ./hello-agent \
  --max-ticks 1 \
  --interval 0 \
  --environment sandbox \
  --auto-approve

You should see one completed tick and a short summary. That is the minimal Aether Forge loop:

Planner -> Policy Gate -> Execute -> Step Ledger -> Memory

Add an LLM Planner

When you want real LLM planning, set a provider key and regenerate or override at run time.

export ANTHROPIC_API_KEY=sk-ant-...
 
forge generate-fast \
  --name "research-agent" \
  --idea "summarize trusted sources into a daily brief" \
  --output ./research-agent \
  --planner-mode anthropic \
  --planner-model claude-sonnet-4-5 \
  --planner-api-key-env ANTHROPIC_API_KEY

If you omit --planner-mode, Aether Forge auto-detects cloud keys first, then local Ollama when no cloud key is set, then heuristic fallback. The resolved planner is saved in aether-forge.json so another machine can run the same agent with the same environment variables.

Add Crypto Features

Crypto is an optional module layer, not required by the core framework.

pip install 'aether-forge[wallet] @ git+https://github.com/HeyElsa/aether-forge.git'
 
forge generate-fast \
  --name "eth-watcher" \
  --idea "monitor ETH market conditions and write observations" \
  --output ./eth-watcher \
  --wallet \
  --planner-mode heuristic

For crypto scaffolds, --environment controls policy and promotion context while --mode controls the trading backend:

# Real market-style path with simulated orders
forge run ./eth-watcher --environment sandbox --mode paper --auto-approve
 
# Live capital path, only after promotion evidence and funding
forge run ./eth-watcher --environment production --mode live

Use from TypeScript

The companion @aether-forge/sdk package validates artifacts and parses planner output from Node, browsers, and edge runtimes. It is intentionally interface-only in v0.1.x; the runtime tick loop remains Python-side.

npm install @aether-forge/sdk
import { assertValid, parsePlannerOutput, validateAgentSpec } from "@aether-forge/sdk";
 
const spec = assertValid(validateAgentSpec(jsonFromDisk));
const plan = parsePlannerOutput(rawLlmResponse);

Next Steps

Last updated on
IntroductionChoose Your Path