Skip to content

Getting Started

Pre-alpha software

AEGIS is at v1.1.0. Everything is implemented and tested (488 tests): control plane, cognitive layer, DAG engine, agents, shared services, API gateway, module system, marketplace with sandboxed execution, web app, CI, observability, containerized deployment, native desktop app (Tauri), Android app (Capacitor), and Whisper STT + Piper TTS voice. Single-user software — APIs may still evolve.

No Python or developer tools required. AEGIS runs as a native desktop app.

Step 1 — Download

Go to the Download page and get the installer for your platform: - Windows — AEGIS_1.1.0_x64-setup.exe - Linux — aegis_1.1.0_amd64.AppImage or .deb

Step 2 — Install

Windows: Run the setup file. Windows may show a SmartScreen warning because the app is not yet from a known publisher — click More info → Run anyway.

Linux AppImage: 

chmod +x aegis_1.1.0_amd64.AppImage
./aegis_1.1.0_amd64.AppImage

Linux .deb: 

sudo dpkg -i aegis_1.1.0_amd64.deb

Step 3 — Get an AI engine

AEGIS needs at least one AI engine to work. The easiest options:

Anthropic API key (cloud): 1. Create an account at console.anthropic.com 2. Go to API Keys → Create key 3. Copy the key — you'll need it in Step 4

Ollama (local, free, no account needed): 1. Download and install Ollama 2. Pull a model: ollama pull llama3.2 (or any model you prefer) 3. Ollama starts automatically — no key needed

OpenAI API key (cloud): 1. Create an account at platform.openai.com 2. API Keys → Create new key 3. Copy the key

Step 4 — Configure AEGIS

On first launch, AEGIS opens a setup screen. You can also edit the .env file directly (found in the installation directory):

# Paste your Anthropic key here (delete the line if not using Anthropic)
ANTHROPIC_API_KEY=sk-ant-...

# Paste your OpenAI key here (delete the line if not using OpenAI)
OPENAI_API_KEY=sk-...

# Ollama: leave blank — AEGIS finds it automatically at localhost:11434
# OLLAMA_BASE_URL=http://localhost:11434

# Pick any API key you'll use to secure your AEGIS server
AEGIS_API_KEY=choose-something-hard-to-guess

Keep your keys private

Never share your .env file. Never paste API keys into chat messages or documents. These keys give billing access to your AI provider account.

Step 5 — Launch AEGIS

Launch AEGIS from the Start menu / applications list. The system initializes, probes your hardware, and opens the web interface in the app window.

You should see the Dashboard — the AEGIS control center. Click the chat icon in the sidebar and type your first message.

Option B — Clone from source (developer)

Use this path if you want to contribute, modify AEGIS, or prefer running from source.

Prerequisites

Requirement Version Notes
Python 3.11+ python.org
Git Any recent version For cloning the repo
Docker + Compose Current stable Optional — only if you run the Odysseus engine

Docker is only needed if you choose to use the optional Odysseus engine. With a cloud API key or a local Ollama model, AEGIS needs no Docker at all.

Download

git clone https://github.com/HeavyWanderer/AEGIS.git
cd AEGIS

Install Python dependencies

python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

pip install -r requirements.txt

Configure your environment

cp .env.example .env

Open .env in any text editor. Add your API key(s) and set AEGIS_API_KEY to any string you choose. See the Configuration manual for every available variable.

Never commit your .env file

.env is gitignored. API keys and credentials must never appear in commits, documentation, or commit messages. This is a governance rule.

Start the system

python main.py

AEGIS boots the control plane, probes your hardware, and starts the API gateway and web app at http://localhost:8600.

Optional: using Odysseus as an engine

Odysseus is one supported engine among several. If you want to use it, clone it as a sibling directory (never inside the AEGIS repo — license boundary):

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
docker compose up -d --build

Then set ODYSSEUS_BASE_URL in your .env.

Verify the startup

When AEGIS starts successfully, you will see the control plane initializing, adapters connecting, and the engine manager probing your hardware. If anything fails to connect, the logs will tell you which component and why.

See Running AEGIS for a full walkthrough of the startup sequence.

What's next?