— docs

Get started

Pick an install method, then run your first engagement.

Docs navigation

Four ways to get AEGIS on your machine. Pick the one that matches your platform — they all land at the same place: a working aegis on your PATH, ready for aegis init.

Python

≥ 3.12

Node

≥ 20 (for TUI)

LLM

Anthropic key / Claude Code

Authorised target

Required

Installation

All four routes give you the same aegis CLI. Skip to whichever matches your machine.

PyPI (any Linux / macOS / WSL)

Cleanest path. Works on every modern Python. pipx is recommended over pip so AEGIS lands in its own isolated venv.

install via pipx bash

pipx install aegis-pentest

…or plain pip bash

pip install aegis-pentest

Arch (AUR) — maintained build

The package ships every release within hours of PyPI. optdepends covers the full tool catalogue so you can install nmap / nuclei / kerbrute / scoutsuite / kube-bench piecemeal.

install via yay bash

yay -S aegis-pentest

…or paru bash

paru -S aegis-pentest

Docker — zero host setup, all tools preinstalled

Kali-rolling base, ~4 GB image, every binary in the catalogue ready to run. Engagement directories mount through; everything else stays sandboxed.

pull pre-built image bash

aegis docker pull

run an engagement bash

export ANTHROPIC_API_KEY=sk-ant-...
aegis docker run engagements/2026-acme

interactive shell bash

aegis docker shell

From source — hack the orchestrator

Editable install. Use this if you're contributing, customising the agent prompts, or wiring in a new tool wrapper. The TUI builds as a separate Node bundle.

clone + editable install bash

git clone https://github.com/glorybnat/aegis-pentest.git
cd aegis-pentest
pip install -e .

build the TUI bash

cd tui && npm install && npm run build

First run, in 60 seconds

Three commands. The third one is where AEGIS does its thing.

01 Profile the host

Detects CPU, memory, OS, and which of the 170+ tools are already installed. Cached to ~/.config/aegis/env-profile.json.

bash bash

aegis init

02 Create an engagement

Scaffolds engagements/<id>-acme/ with a scope.yaml that pins exactly what AEGIS may touch.

bash bash

aegis engagement new \
  --client "Acme Corp" \
  --scope www.acme.com,api.acme.com \
  --budget-usd 5.00

03 Run

The TUI takes over. Watch the activity feed for tools running; the right pane for what Claude is reasoning about.

bash bash

aegis run engagements/2026-acme

What's next

You're installed. The rest of the docs go deeper on each surface.

walkthrough

Your first engagement

Run AEGIS against a deliberately vulnerable target with operator guidance.

Continue →

operate

Operator controls

Slash commands, reasoning verbs, mid-engagement steering.

Continue →

operate

Scope & safety

How AEGIS keeps you inside the engagement and inside the law.

Continue →

develop

Architecture

What the orchestrator actually does under the hood.

Continue →

reference

CLI reference

Every aegis command, every flag, every behaviour.

Continue →

develop

Extending

Add a new tool wrapper, a new chain rule, a new probe.

Continue →