aegis-stack 0.5.4

A production-ready Python foundation for builders who refuse to wait. Try: uvx aegis-stack init my-project

You need to ship reliable software, but management only gave you 2 weeks.

No time for health checks, proper testing, or clean architecture. Just enough time for duct tape and hope.

What if you could go from idea to working prototype in the time it takes to grab coffee?

Aegis Stack is a system for creating and evolving modular Python applications over time, built on tools you already know.

Prerequisites

• Python 3.11+
• Docker & Docker Compose - Required for the standard development workflow (make serve). Generated projects use Docker for consistent environments and service dependencies (Redis for workers, health monitoring, etc.).

Quick Start

# Run instantly without installation
uvx aegis-stack init my-api

# Create with user authentication
uvx aegis-stack init user-app --services auth

# Create with background processing
uvx aegis-stack init task-processor --components scheduler,worker

# Start building
cd my-api && uv sync && cp .env.example .env && make serve

Installation alternatives: See the Installation Guide for uv tool install, pip install, and development setup.

Overseer - Built-In System Visibility

Overseer is the built-in system dashboard that ships with every Aegis Stack project.

It provides a live view of what your application is doing at runtime - across core components (Backend, Database, Workers, Scheduler) and services (Auth, AI, Comms) - through a web UI.

Overseer goes beyond simple health checks. You can inspect worker queues, scheduled jobs, database state, and AI usage, all in one place, without wiring up external tools.

No Datadog. No New Relic. No vendor lock-in.

Just a clear view of your system, included from day one.

CLI - First-Class System Interface

The Aegis CLI is a first-class interface to your running system.

It goes beyond simple health checks, exposing rich, component-specific commands for inspecting and understanding your application from the terminal.

Query worker queues, scheduler activity, database state, AI usage, and service configuration, all without leaving the CLI.

The same system intelligence that powers Overseer and Illiana is available here, optimized for terminal workflows.

Illiana - Optional System Operator

When the AI service is enabled, Aegis exposes an additional interface: Illiana.

Illiana is a conversational interface that answers questions about your running system using live telemetry and optional RAG over your codebase.

She is not required to use Aegis Stack, and nothing in the system depends on her being present. When enabled, she becomes another way, alongside the CLI and Overseer, to understand what your application is doing and why.

Your Stack Grows With You

Your choices aren't permanent. Start with what you need today, add components when requirements change, remove what you outgrow.

# Monday: Ship MVP
aegis init my-api

# Week 3: Add scheduled reports
aegis add scheduler --project-path ./my-api

# Month 2: Need async workers
aegis add worker --project-path ./my-api

# Month 6: Scheduler not needed
aegis remove scheduler --project-path ./my-api

# Stay current with template improvements
aegis update

Starter	Add Later?	Remove Later?	Git Conflicts?
Others	❌ Locked at init	❌ Manual deletion	⚠️ High risk
Aegis Stack	✅ One command	✅ One command	✅ Auto-handled

Most starters lock you in at init. Aegis Stack doesn't. See Evolving Your Stack for the complete guide.

Available Components & Services

Components (infrastructure)

• Core → FastAPI + Pydantic V2 + Uvicorn
• Database → Postgres / SQLite
• Cache/Queue → Redis
• Scheduler → APScheduler
• Worker → Arq / Taskiq

Services (business logic)

• Auth → JWT authentication
• AI → PydanticAI / LangChain
• Comms → Resend + Twilio

Components Docs → | Services Docs →

Learn More

• CLI Reference - Complete command reference
• About - The philosophy and vision behind Aegis Stack
• Evolving Your Stack - Add/remove components as needs change
• Technology Stack - Battle-tested technology choices

For The Veterans

No reinventing the wheel. Just the tools you already know, pre-configured and ready to compose.

Aegis Stack respects your expertise. No custom abstractions or proprietary patterns to learn. Pick your components, get a production-ready foundation, and build your way.

Aegis gets out of your way so you can get started.