Aetheris
July 4, 2026 · View on GitHub
The reliability layer your AI agents are missing.
Your agent is processing 1,000 customer records. It reaches record 847 — and the process dies.
Without Aetheris: start over from record 1. Re-run 847 LLM calls. Pay twice. Pray nothing was written twice.
With Aetheris: restart. It resumes from recorded progress. Runtime Tool side effects are not repeated when the production Ledger and Effect Store are configured.
The problem with AI agents in production
Every production AI agent eventually hits the same three walls:
| Failure mode | What happens today |
|---|---|
| Process crash mid-task | Restart from the beginning; re-run all LLM calls |
| Retry after tool failure | Email sent twice, order created twice, payment charged twice |
| "Why did the AI do that?" | No visibility, no audit trail, no replay |
Aetheris is an open-source runtime that solves all three — without requiring you to rewrite your agent.
Production Proof
"Production-ready" is not a claim — it's a testable assertion.
| Evidence | Status | Link |
|---|---|---|
| Crash Recovery Demo | ✅ | examples/crash_recovery/ |
| Grafana Dashboard | ✅ | deployments/compose/grafana/ |
| k6 Load Test (100 concurrent) | ✅ | benchmarks/k6/ |
| Go Benchmark (JobStore) | ✅ | benchmarks/reports/ |
| Runtime Guarantees Matrix | ✅ | docs/guides/runtime-guarantees.md |
Quick verification:
# Start the full observability stack
make docker-run
# Run benchmarks
make test
go test -tags benchmark -bench=. ./internal/runtime/jobstore/
# Try crash recovery
cd examples/crash_recovery && python demo.py
Architecture
Aetheris is the L1 execution layer in a four-layer Agent infrastructure stack:
┌─────────────────────────────────────────────┐
│ L3: Governance (hermesx) │
│ Policy · Compliance · Audit · Multi-tenant │
├─────────────────────────────────────────────┤
│ L2: Orchestration (superagent-base) │
│ Agent Lifecycle · Workflow Composition │
├─────────────────────────────────────────────┤
│ L1: Execution (Aetheris) ◀── You are here │
│ Durable Jobs · Crash Recovery · Event Log │
├─────────────────────────────────────────────┤
│ L0: Capabilities (Oris / OpenHuman) │
│ LLMs · Tools · Data Sources · External API │
└─────────────────────────────────────────────┘
What Aetheris owns:
- Event-sourced job execution with crash recovery
- At-most-once tool execution via idempotency ledger
- Lease-fenced multi-worker scheduling
- Evidence signing and forensics read model
- RoutingAdvisor for capability-level routing decisions
What Aetheris delegates:
- Governance policies → L3 (hermesx)
- Agent lifecycle management → L2 (superagent-base)
- LLM inference and tool execution → L0 (Oris)
Integration contracts are defined in:
Quickstart — no Docker required
Requirements: Go 1.26.1+, Git
git clone https://github.com/Colin4k1024/Aetheris.git
cd Aetheris
make run-embedded # starts with embedded SQLite, no external services
curl http://localhost:8080/api/health # {"status":"ok", ...}
From Python (pip install aetheris):
from aetheris import AetherisClient
client = AetherisClient("http://localhost:8080")
job = client.run("my-agent", "Summarize the Q3 earnings report")
result = job.wait()
print(result.output)
From any language — Aetheris exposes a REST API. Wrap your existing agent with two config lines:
# configs/api.embedded.yaml
agents:
agents:
my_python_agent:
type: "external_http"
external:
url: "http://localhost:9000/invoke"
timeout: "120s"
Then submit a job:
curl -X POST http://localhost:8080/api/agents/my_python_agent/message \
-H "Idempotency-Key: task-001" \
-H "Content-Type: application/json" \
-d '{"message": "Process customer batch #42"}'
Verified README scenario GIFs
These GIFs were generated from a real local run of the README quickstart and
external_http batch demo. The raw evidence is available in
artifacts/readme-scenario-proof.
Embedded quickstart health check
external_http durable batch job
Event log and trace proof
Core guarantees
1. Crash recovery
Every job step is checkpointed. If the worker dies, the next worker picks up from the last checkpoint — not the beginning.
Job progress: ████████████████████░░░░░░░░░░ (step 16/25)
Worker crash! 💀
Restart: ████████████████████ (resumes at step 16)
2. At-most-once Runtime Tool boundary
External API calls implemented as Aetheris Runtime Tools (payments, emails, order creation) are wrapped in an invocation ledger and Effect Store. If a step is retried after a recorded commit, the runtime injects the recorded result instead of repeating the side effect.
# Without Aetheris: retry → email sent twice
# With Aetheris Runtime Tool: retry → ledger returns recorded result, email send is not repeated
3. Full decision audit trail
Every LLM call, tool invocation, and checkpoint is appended to an immutable event log. You can replay any job from any point — without re-calling LLMs or external APIs.
aetheris trace <job-id> # view the full decision timeline
aetheris replay <job-id> # replay without side effects
Guarantees are configuration-dependent. See the guarantee matrix for the exact boundary between embedded mode, external_http, native Runtime Tools, and production Postgres deployments.
Connect your existing agent
Aetheris works with any agent, in any language. You don't need to change your agent code.
For split API/Worker deployments, load the same external_http agent definition into both processes so the API can accept /api/agents/:id/message and the Worker can execute the job.
Python (LangChain / any agent)
# Your existing LangChain agent — unchanged
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent
agent = create_react_agent(ChatOpenAI(), tools, prompt)
# Expose it as an HTTP endpoint (one function)
from aetheris.integrations.langchain import serve
serve(agent, port=9000) # Aetheris will call this endpoint durably
agents:
agents:
my_langchain_agent:
type: "langchain"
external:
url: "http://localhost:9000/invoke"
When you need Aetheris to own LangChain/LangGraph internal steps, switch to embedded mode and expose an explicit manifest from the Python adapter:
agents:
agents:
my_langchain_agent:
type: "langchain"
external:
mode: "embedded"
url: "http://localhost:9000"
manifest_path: "./configs/framework-agents/my_langchain_agent.manifest.json"
→ Full LangChain integration guide
Any HTTP service
# Add to configs/api.embedded.yaml
agents:
agents:
my_agent:
type: "external_http"
external:
url: "http://your-agent:9000/invoke"
Your agent receives a job envelope with message, job_id, and idempotency_key. It returns {"answer": "...", "final": true}.
Go (Eino / native)
// Built-in via AgentFactory — config-driven
// configs/agents.yaml
agents:
my_eino_agent:
type: "react"
llm: "default"
tools: ["web_search", "calculator"]
How it works
Your Agent (Python/JS/Go/any)
│
▼
Aetheris API ──── idempotency key ──▶ Invocation Ledger
│ (Runtime Tool boundary)
▼
Durable Worker ──── checkpoint ──────▶ Event Store
│ (crash recovery)
▼
Trace & Replay API ───────────────────────────────▶ Audit
The runtime is event-sourced: every state transition is an append-only event. With the production Ledger and Effect Store configured, replay injects recorded LLM and Runtime Tool results instead of re-calling them.
vs. LangGraph Platform / Temporal / vanilla frameworks
| Aetheris | LangGraph Platform | Temporal | |
|---|---|---|---|
| Open source + self-hosted | ✅ | ❌ (cloud only) | ✅ |
| No infrastructure for local dev | ✅ (embedded SQLite) | ❌ | ❌ (requires server) |
| At-most-once Runtime Tool boundary | ✅ with Ledger + Effect Store | ⚠️ manual | ⚠️ activity/idempotency dependent |
| Works with any agent framework | ✅ | ❌ LangGraph only | ❌ requires SDK |
| LLM decision audit trail | ✅ | ✅ | ❌ |
| Replay without re-calling recorded LLM/Tool effects | ✅ with Effect Store | ⚠️ checkpoint-dependent | ✅ for recorded workflow history |
Explore the external_http batch demo
See the current black-box adapter boundary in 2 minutes:
cd examples/crash_recovery
pip install aetheris
python demo.py
# Starts a local external_http demo agent and submits one durable batch job
The example shows durable submission and trace visibility around one external HTTP call. For true per-step checkpoint resume inside the work itself, use native Aetheris tools/workflows instead of a single external_http call.
Repository map
| Path | Purpose |
|---|---|
| cmd/api | HTTP API service |
| cmd/worker | Background job worker |
| cmd/cli | CLI: aetheris trace/replay/jobs/chat |
| configs | Runtime configs (embedded, Docker, production) |
| examples | Working examples for each integration pattern |
| sdk/python | Python SDK (pip install aetheris) |
| docs | Guides, API reference, design notes |
| internal/agent | Core runtime engine |
Documentation
License
Apache 2.0 — free to use, self-host, and modify.