One command installs a complete AI agent that lives in your terminal, talks to any model, runs on your machine, and learns as it goes. AEGIS is an open, self-hostable alternative to Hermes Agent and OpenClaw — with their capabilities in ~11k auditable lines instead of hundreds of thousands.
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bash
aegis
| What it means | |
|---|---|
| 🪶 Tiny, auditable core | ~11k lines you can actually read and trust. OpenClaw is ~434k; Hermes is huge. Same capability, none of the sprawl. |
| 🔌 Truly model-agnostic | 26 providers (Claude, GPT, Gemini, Llama, DeepSeek, Qwen, local Ollama…) behind one interface, with API-key and OAuth login, fallback chains, credential pools, and per-prompt routing. |
| 🧠 It actually learns | A real closed loop — reviews finished sessions, extracts memory + skills (redacted), and promotes them on your approval. Plus FTS5 cross-session recall. |
| 🛡️ Safe by default | A permission cascade with a hardline blocklist (refuses rm -rf / even in yolo), pre-exec scanning, fail-closed docker/ssh/singularity/modal sandboxes, and untrusted-tool-result wrapping against prompt injection. |
| 📡 Everywhere you are | One agent serving CLI, Telegram, Discord, Slack, Signal, Matrix, Email, and webhooks — with voice-memo transcription and a durable, retrying delivery queue. |
| 🧰 Batteries included | 30 tools, 24 skills + hub import, MCP (client and server), an OpenAI-compatible API, a web dashboard, cron, and a one-line installer. |
| 🔓 Yours | MIT, self-hosted, no subscription, no lock-in. Your keys, your data, your machine. |
Built in the spirit of NanoClaw: do what Hermes and OpenClaw do, but keep the whole thing small enough to understand in an afternoon.
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bashThe installer (like Hermes/OpenClaw) finds Python 3.10+, builds an isolated venv
at ~/.aegis/venv, installs the full curated AEGIS stack (.[all]) by default,
drops a global aegis launcher on your PATH, installs Playwright Chromium for
browser tools, and grabs ripgrep if missing. When a terminal is attached it
immediately launches the guided onboarding flow (provider, OAuth/API key, model,
web tools, optional channels, dashboard, and workspace files) using /dev/tty,
so curl | bash prompts work correctly. In a real terminal it uses arrow-key
menus and Space-toggle checkboxes; in scripts it falls back to simple text prompts.
Onboarding is included by default. Headless automation can opt out with
--no-prompt, --skip-onboard, or AEGIS_ONBOARD=0. Use --core for a smaller
CLI-only install, or --skip-browser to skip the Chromium download.
Windows: irm …/install.ps1 | iex.
Everything in one go:
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bash -s -- --advanced
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bash -s -- --verify
curl -fsSL https://raw.githubusercontent.com/Alien0013/aegis/main/install.sh | bash -s -- --coreFrom a clone, or for development:
git clone <repo> aegis && cd aegis
./install.sh # one-line, isolated, global command
# — or the manual/editable route —
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[all]" # core + every extra
playwright install chromium # if you took the browser extra
aegis doctorKeep it current with aegis update. Remove with ./uninstall.sh (--purge to also
delete ~/.aegis). Optional extras: .[browser], .[computer], .[discord],
.[slack] — everything else (providers, OAuth, MCP, marketplace, gateway, serve,
voice) is in the core install.
# 1. run or re-run guided onboarding
aegis setup
# or point it at a provider manually
aegis config set ANTHROPIC_API_KEY sk-ant-... # Claude
aegis config set OPENAI_API_KEY sk-... # OpenAI
aegis auth login openai # …or OAuth instead of a key
aegis model set ollama llama3.1 # …or fully local, no key
# 2. talk to it
aegis # interactive REPL (streaming, slash commands)
aegis chat -q "summarize the files in this folder"
aegis chat --continue # resume your last session
# 3. run it as a service on chat platforms
export TELEGRAM_BOT_TOKEN=...
aegis gateway --channels telegram,clianthropic, openai, google (Gemini), openrouter, groq, deepseek,
xai, mistral, together, ollama, lmstudio, plus any OpenAI-compatible
endpoint via model.base_url and custom_providers in config.
Auth resolution per provider: explicit base_url → API key from the environment →
OAuth login (if usable for model requests). API keys intentionally win when both
exist because some OAuth tokens are identity-only. Inspect it with aegis auth status.
OAuth is implemented generically (PKCE S256, client_secret support,
localhost-callback and manual-paste flows, automatic refresh, auth.json at
chmod 0600, token quarantine on failure). Anthropic, OpenAI (ChatGPT/Codex
login), and Google (Gemini login) ship with OAuth configs:
aegis auth login anthropic # browser → paste code
aegis auth login openai # ChatGPT login, localhost:1455 callback
aegis auth login google # Google sign-in, loopback callbackOpenAI login + token storage/refresh can succeed while the token lacks the
model.request scope needed for inference; AEGIS detects that and falls back to
API-key auth when available. API keys remain the reliable OpenAI path. Any other
IdP wires up by overriding OAuthConfig.
Built-ins: read_file, write_file, edit_file, list_dir, glob, search,
bash, web_fetch, web_search, todo_write, memory, skill,
spawn_subagent, generate_image, execute_code (RPC sandbox), browser
(Playwright), computer (pyautogui), plus every connected MCP tool
(mcp__<server>__<tool>) and any plugin tools.
Every tool with a danger group (fs, runtime, network) flows through a
permission cascade: deny_groups → exec mode (deny | allowlist | ask | auto | full) → allowlist prefixes → interactive approval. Read-only tools are always
allowed. Set the policy with aegis config set tools.exec_mode ask (or pass
--yolo to auto-approve a session).
- Memory —
~/.aegis/memories/{MEMORY.md,USER.md}(§-delimited, char-capped, atomic writes) plus an append-onlyhistory.jsonl. The agent persists facts via thememorytool; a frozen snapshot keeps the system prompt cache-stable. Pluggable external backends: setmemory.providertohoncho(pip install honcho-ai),mem0(pip install mem0ai), orjsonl(zero-dep) — they layer on top of the always-on file memory. - Skills —
SKILL.mdpackages (agentskills.io-compatible frontmatter) loaded with progressive disclosure and tiered precedence (workspace > personal > configured > bundled).aegis skills new <name>scaffolds one;requires.{env,bins,os}gates availability.
Drop these into ~/.aegis/workspace/ (global) or your project root (local, wins):
SOUL.md— persona / toneAGENTS.md(or.aegis.md/CLAUDE.md) — operational rulesUSER.md— facts about you
Connect any MCP server (stdio or Streamable HTTP); their tools appear to the agent
as mcp__<server>__<tool> and flow through the same permission cascade.
aegis mcp add filesystem "npx -y @modelcontextprotocol/server-filesystem /tmp"
aegis mcp test # connect + list tools for each server
aegis mcp listAlso reads a Claude-Desktop-format ~/.aegis/mcp.json ({"mcpServers": {...}}).
One agent, many surfaces: cli, telegram (core), discord, slack (extras).
export TELEGRAM_BOT_TOKEN=... # or DISCORD_BOT_TOKEN / SLACK_*_TOKEN
aegis gateway --channels telegram,discord,slackPer-conversation sessions, control commands (/new, /status), and an optional
cron ticker.
aegis skills search pdf # query the agentskills.io registry
aegis skills install git:owner/repo # clone a repo of SKILL.md packages
aegis skills install git:owner/repo@main/skills/foo # a subdir at a ref
aegis skills install ./local/skill-dir # a local package
aegis skills remove fooInstalls are tracked in ~/.aegis/skills/.lock.json (source + SHA-256 digest).
The agent can write a Python script that orchestrates many tool calls; the child process reaches tools over a Unix socket and only its stdout returns to the model — collapsing multi-step pipelines into one cheap turn. Secrets are stripped from the child env.
aegis serve --port 8790 # POST /v1/chat/completions, GET /v1/modelsPoint any OpenAI client at it; AEGIS (tools, memory, skills) runs behind the API.
aegis cron add "@daily" "summarize today's git commits and email me"
aegis cron add "30m" "check CI and report failures"
aegis cron run # start the scheduler (or it ticks inside the gateway)Drop a *.py into ~/.aegis/plugins/ exporting register(api) to add tools,
channels, or providers with no core edits.
Bounded synchronous loop (max_iterations, default 50) with a final grace call
for a summary; three-tier system prompt (stable / context / volatile) rebuilt only
on compaction; message governance (orphan-drop + backfill) before every call;
concurrent tool execution (≤8 workers); LLM compaction preserving the first 3 and
last 20 turns.
aegis/
providers/ transports (chat_completions, anthropic) + auth (key, OAuth)
tools/ base, permissions, registry, builtin
agent/ context, governance, compaction, loop, agent
memory.py skills.py session.py (SQLite)
gateway/ runner + channels (cli, telegram)
cli/ main (subcommands) + repl (TUI)
builtin_skills/web-research/SKILL.md
tests/test_smoke.py
aegis [chat|model|auth|setup|onboard|update|completion|skills|mcp|serve|cron|tools|memory|config|sessions|gateway|doctor|backup|import|insights|webhook|hooks|kanban|curator|dashboard|acp|pairing|checkpoints|background]
— run any with -h. aegis alone opens the REPL. chat flags: --resume,
--continue, --worktree/-w, --yolo, --model, --provider, --image.
Slash commands in the REPL: /usage /compress /background /rollback /personality /model /tools /skills /memory /sessions /new.
Everything keys off APP_NAME/the package name. To rebrand: rename the aegis/
package dir, update pyproject.toml (name, [project.scripts]), and the
APP_NAME constants. The runtime home is $AEGIS_HOME or ~/.aegis.
pip install -e ".[dev]"
pytest -q # runs fully offline against a fake providerMIT.