aeon

README

Aeon

A self-evolving, system-level AI agent that lives inside your kernel.
Not a chatbot. Not an informer. A virtual sysadmin that acts on your behalf.

Install · Get Started · Configuration · Commands · Deployment · Uninstall

Engineering Deep Dive · Development

---

Beta: v0.0.1-beta. APIs and config format may change.

What is Aeon?

Aeon is a system-level AI agent with deep Linux/Unix integration. It has root access guarded by a sandboxed security policy. It's self-evolving, self-learning, and self-correcting — a general-purpose agent that does things, not a chatbot that talks about them.

It starts with core tools (shell, files, memory, cron) and grows by writing its own Python skills. Single Go binary, no CGO, no runtime dependencies. Runs as a Telegram bot or local CLI.

---

Install

curl -sSL https://raw.githubusercontent.com/ImJafran/aeon/main/deploy/install.sh | bash

The script installs Go (if needed), builds Aeon, and runs aeon init to set up everything.

Other install methods

Using go install

Requires Go 1.24+.

go install github.com/ImJafran/aeon/cmd/aeon@latest

From source

git clone https://github.com/ImJafran/aeon.git
cd aeon
make install    # builds + installs to ~/.local/bin/aeon

---

Get Started

# 1. First-time setup — installs Python, ffmpeg, creates config
aeon init

# 2. Add your API keys
nano ~/.aeon/config.json

# 3. Run
aeon              # interactive CLI
aeon serve        # Telegram daemon

That's it. aeon init detects your system, installs missing dependencies, sets up the workspace, and generates a config file.

$ aeon init

🌱 Aeon v0.0.1-beta — First-Time Setup
========================================

[1/4] Checking system...
  ✓ OS: linux (amd64)
  ✓ SQLite: compiled into binary
  ✗ Python: not found
  ✗ ffmpeg: not found

[2/4] Installing dependencies...
  ✓ Python installed: Python 3.12.3
  ✓ ffmpeg installed

[3/4] Detecting LLM providers...
  ✓ ANTHROPIC_API_KEY set
  ✓ GEMINI_API_KEY set

[4/4] Setting up workspace...
  ✓ Workspace created at ~/.aeon
  ✓ Config written to ~/.aeon/config.json
  ✓ Base Python environment ready

✓ Setup complete!

---

Configuration

All config lives in ~/.aeon/config.json. See config.example.json for the full template.

Note: After editing the config, restart Aeon to apply changes:

# If running as a systemd service
sudo systemctl restart aeon

# If running manually, just Ctrl+C and re-run
aeon serve

{
  "provider": {
    "zai": {
      "enabled": true,
      "api_key": "your-zai-api-key",
      "default_model": "glm-4.7"
    },
    "anthropic": {
      "enabled": true,
      "api_key": "sk-ant-your-key",
      "default_model": "claude-sonnet-4-6"
    },
    "gemini": {
      "enabled": true,
      "api_key": "your-gemini-key",
      "default_model": "gemini-2.5-flash-lite"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "your-telegram-bot-token",
      "allowed_users": [0]
    }
  },
  "routing": {
    "primary": "zai",
    "fast": "anthropic_fast",
    "fallback": "gemini"
  }
}

Supported Providers

Provider	Notes
Z.ai	GLM models via OpenAI-compatible API (default)
Anthropic	Claude models via native Messages API
Gemini	Also handles voice transcription and TTS
Ollama	Fully offline, local models
Any OpenAI-compatible	LM Studio, vLLM, OpenRouter, etc.

Telegram Bot Setup

1. Message @BotFather -> /newbot
2. Copy the token into config.json -> channels.telegram.bot_token
3. Get your user ID from @userinfobot
4. Add it to channels.telegram.allowed_users
5. Restart Aeon

---

Commands

Command	Description
/status	System info — provider, tools, memory, active tasks
/model	Switch LLM provider at runtime
/model gemini	Switch to a specific provider
/new	Clear conversation history (memory persists)
/stop	Cancel running tasks
/skills	List evolved skills
/help	List available commands

---

Deployment

As a systemd Service

sudo cp deploy/aeon.service /etc/systemd/system/
sudo systemctl enable --now aeon

---

Uninstall

Removes the binary, ~/.aeon/ (config, database, skills, logs), and systemd service:

aeon uninstall

If you cloned the source, remove it separately: rm -rf /path/to/aeon

---

More

• Engineering Deep Dive — architecture, comparison with other agents, tools, skills, security model, performance, troubleshooting
• Development — how to contribute, build & test, branch naming, PR workflow

---

Author

Created by Jafran Hasan (@imjafran)

License

MIT