aetherheart-ai/aeloon

English | 中文

---

What is Aeloon?

Aeloon is a lightweight, high-performance, and modular AI agent framework featuring graph-driven parallel acceleration and flexible hot-swappable plugins for many usages (Deep research, Wiki, SkillGraph, ACP Bridge and StatusPannel).

Core philosophy: one agent, all platforms, self-hosted data, privacy first.

---

✨ Key Features

---

🚀 Quick Start

One-Click Install

curl -fsSL https://raw.githubusercontent.com/AetherHeartAI/Aeloon/main/install.sh | bash

The installer walks you through provider and channel setup interactively. Offline and source installs are also supported:

# Install from local source
bash install.sh --from-source

# Install a specific version
bash install.sh --version v1.0.0

# Offline mode (requires local wheel)
bash install.sh --offline

Manual Install

# Install from source
git clone https://github.com/AetherHeartAI/Aeloon.git
cd Aeloon
pip install -e .

# First-time config
aeloon onboard

Build a wheel

# Output to dist/ by default
bash scripts/build_wheel.sh

# Use a custom directory and clear old artifacts
bash scripts/build_wheel.sh ./artifacts --clear

First Conversation

# One-shot CLI chat
aeloon agent -m "Hello Aeloon."

# Start gateway mode (connects all channels)
aeloon gateway

# Check channel status
aeloon channels status

---

🔌 Channel Support

WeChat and Feishu support QR scan login out of the box (/wechat login, Feishu in-app auth).

Other channels: Telegram, DingTalk, WeCom, Slack, Discord, QQ, Email, WhatsApp, Matrix.

All channels inherit BaseChannel and are auto-discovered — drop a file in aeloon/channels/ and it works, no registration needed.

---

🤖 Provider Support

Major LLMs with one-click setup: OpenAI, Anthropic, DeepSeek, Gemini, Zhipu, Moonshot, MiniMax, Groq, OpenRouter (free tier included), Azure OpenAI, Ollama, vLLM, plus OAuth-based OpenAI Codex / GitHub Copilot.

Selection priority: explicit name → model keyword match → API key prefix → API base match.

---

🔧 Tool System

---

📝 Skill System

Pure Markdown — extend agent capabilities with zero code. Drop a SKILL.md into .aeloon/skills/ and it’s injected into the system prompt. Built-in skills cover scheduling, doc conversion, GitHub, memory, summarization, terminal, and more.

---

🔌 Plugin System

Plugins are modular components that extend Aeloon’s core: custom slash commands, agent tools, background services, message middleware, status bar contributions, and isolated config/storage namespaces.

Plugin types:

• Task Plugin (commands + middleware) — request-response workflows, e.g. /sr, /se
• Hybrid Plugin (commands + tools + services) — long-running agents, e.g. market monitoring
• Service / Status Plugin (services or status bar contributions) — service-style extensions or CLI status bar contributions, e.g. StatusPannel

Built-in plugins:

Lifecycle: Discover → Validate → Register → Commit → Activate → Running → Deactivate

Five-step dev paradigm: Extend Plugin → Implement register(api) → Implement activate() → Write handlers → Create aeloon.plugin.json manifest.

Full development guide: aeloon/plugins/README.md.

---

🐳 Docker Deployment

# Gateway mode
docker compose up

# CLI interactive mode
docker compose run --rm aeloon-cli

Default docker-compose.yml configuration:

• Gateway port: 18790
• Config mount: ~/.aeloon:/root/.aeloon
• Resource limits: 1 CPU / 1GB memory

---

⚙️ Configuration

Config lives at ~/.aeloon/config.json and supports camelCase aliases. Loading precedence:

--config flag  >  AELOON_CONFIG env var  >  ~/.aeloon/config.json

Minimal example:

{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "deepseek/deepseek-r1:free"
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-..."
    }
  }
}

---

🧪 Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific tests
pytest tests/test_kernel.py
pytest -k "telegram"

# Lint + auto-fix
ruff check --fix .

# Format
ruff format .

Requirements: ruff==0.15.6 (CI enforced), Python ≥ 3.11, type hints on all public functions, async/await preferred for I/O.

Commit Convention

Uses Conventional Commits:

(): 

Types: feat, fix, chore, docs, test, refactor, perf, ci

---

🔒 Security

• Network policy: _network_safety.py restricts reachable URLs to prevent SSRF
• Execution sandbox: Shell tool uses policy controls for allowed commands
• API key isolation: Keys stored in config, never logged
• Channel auth: Each channel supports allowFrom whitelisting
• MCP security: MCP connections can configure allowed tool scopes

---

📜 License

MIT License © 2026 Aether Heart contributors

---