Skip to content

Running AEGIS

Startup sequence

AEGIS starts in a defined order. If a component fails to initialize, it logs the error and stops — it will not silently continue in a broken state.

Step 1 — Activate your virtual environment:

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Step 2 — Start AEGIS:

python main.py

Reading the startup output

When AEGIS starts, you will see each layer initialize in sequence. A successful startup looks roughly like this:

[AEGIS] Config loaded
[Core] Orchestrator initialized
[Core] Service Registry ready
[Core] Permission System active
[Core] Module Loader ready
[Core] Event Bus started
[Cognitive] Probing hardware...
[Cognitive] Engine Manager: GPU detected / RAM: 32GB
[Cognitive] Adapter: anthropic — READY
[Cognitive] Adapter: ollama — READY
[Cognitive] Memory layer initialized
[Cognitive] Knowledge Graph loaded
[Cognitive] Safety Layer active
[AEGIS] Control plane is live

If any component fails, the log will show the component name, the error, and in most cases a hint about what is missing or misconfigured.

Common startup issues

Missing API key for an engine If an adapter is configured but the API key is missing or invalid, AEGIS will log a warning and skip that adapter. The system will continue with whatever engines are available. If no engines are available, it will log an error.

.env not found Copy .env.example to .env and fill in your values. See Configuration.

Stopping AEGIS

Press Ctrl+C in the terminal where main.py is running (or type /quit). AEGIS will handle the shutdown signal, export memory, close connections cleanly, and flush any pending state.

If you run the optional Odysseus engine, stop it separately: docker compose down in its own directory.

Logs

Runtime logs are written to runtime/logs/. The log level can be adjusted in .env. Log files are gitignored — they are local to your machine.

To follow the live log output (if you're not watching the terminal): 

tail -f runtime/logs/aegis.log

What to do if something breaks

  1. Check the terminal output for the specific component and error message.
  2. Check runtime/logs/ for more detail.
  3. Verify your .env is complete and correct.
  4. If the issue persists, open an issue with the relevant log lines.