Aegis Logo DarkAegis Docs

Installation

A step-by-step guide to install Aegis on your system.

Installation Overview

You can install Aegis using either standard Python 3.13 or UV.

  • New or beginner users: Use standard Python for simplicity.
  • Advanced users or those who prefer faster package management: UV is optional and can simplify dependency installation.

Below, we’ll walk through the installation process while noting differences where applicable.

Prerequisites

Check your Python version:

python3 --version

or

python3.13 --version
python --version

or

py -3.13 --version

If the output doesn't show Python 3.13.x, follow the Python Setup Guide or install uv from the uv installation page.

Create an Aegis Directory

You can create this folder using either your file explorer or the terminal. Name it whatever you like. Just make sure the folder name does not contain spaces, as this can sometimes cause issues with the client.

Examples:

mkdir aegis

or

mkdir cpsc-383-aegis

Run all the commands shown below inside the aegis directory you created.

Create a Virtual Environment

Virtual environments isolate project dependencies from your system Python.

Python Users

Use python3 if it points to version 3.13, otherwise specify python3.13:

python3 -m venv .venv

or

python3.13 -m venv .venv

Use python if it points to version 3.13, otherwise specify py -3.13:

python -m venv .venv

or

py -3.13 -m venv .venv

UV Users

uv venv --python 3.13 .venv

Activate the Virtual Environment

source .venv/bin/activate

Once activated, you can use the python executable (it will point to the venv’s interpreter).

Deactivate Virtual Environment

To deactive a virtual environment, simply run the following command in your terminal, deactivate.

Download Aegis

Python Users

pip install aegis-game

UV Users

uv pip install aegis-game

Initialize

aegis init

If you are initializing the mas assignment use:

aegis init --type mas

Failed Client Download

If the client fails to download, you can manually download the latest release from Aegis GitHub Releases.

Look for the latest client-vx.x.x tag and download the client for your operating system.

Make sure you also add the client app/executable under the client folder show below.

Confirm Installation

If everything installed correctly, your folder structure should look like this for the pathfinding assignment:

aegis
agents
agent_path
main.py
client
<client for your system>
config
config.yaml
worlds
<world1>.world
<world2>.world
<world3>.world
...

Like this for the mas assignment:

aegis
agents
agent_mas
main.py
client
<client for your system>
config
config.yaml
prediction_data
testing
x_test_symbols.npy
y_test_symbols.npy
training
x_train_symbols.npy
y_train_symbols.npy
worlds
<world1>.world
<world2>.world
<world3>.world
...

Update Stub File

The aegis init command creates a default config.yaml. If your professor provided a modified config.yaml, replace the default with their version before proceeding.

Next, run:

aegis forge

This updates your stub file for the assignment, providing proper LSP typing and hiding unnecessary functions, so you can focus only on what’s required.

Head over to this page to learn how to run a game.