https://github.com/lbedner/aegis-stack
A production-ready FastAPI platform with modular components and a built-in control plane.
https://github.com/lbedner/aegis-stack
asyncio boilerplate cli copier copier-template docker fastapi fastapi-starter fastapi-template langchain llm project-template pydantic-ai python rag scaffolding starter-kit uv
Last synced: about 2 months ago
JSON representation
A production-ready FastAPI platform with modular components and a built-in control plane.
- Host: GitHub
- URL: https://github.com/lbedner/aegis-stack
- Owner: lbedner
- License: mit
- Created: 2025-04-27T22:56:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-13T21:18:01.000Z (2 months ago)
- Last Synced: 2026-04-13T23:15:56.165Z (2 months ago)
- Topics: asyncio, boilerplate, cli, copier, copier-template, docker, fastapi, fastapi-starter, fastapi-template, langchain, llm, project-template, pydantic-ai, python, rag, scaffolding, starter-kit, uv
- Language: Python
- Homepage: https://lbedner.github.io/aegis-stack/
- Size: 180 MB
- Stars: 99
- Watchers: 2
- Forks: 7
- Open Issues: 92
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/lbedner/aegis-stack/actions/workflows/ci.yml)
[](https://github.com/lbedner/aegis-stack/actions/workflows/docs.yml)
[](https://www.python.org/downloads/)
[](https://github.com/copier-org/copier)
[](https://pypi.org/project/aegis-stack/)
[](https://pepy.tech/project/aegis-stack)
[](https://clickpy.clickhouse.com/dashboard/aegis-stack?min_date=2026-01-01&max_date=2026-12-31)
[](https://github.com/lbedner/aegis-stack/commits)
[](https://github.com/lbedner/aegis-stack/commits)
[](https://github.com/lbedner/aegis-stack/commits)
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?**
A production-ready FastAPI platform with modular components and a built-in control plane.
## 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
```bash
# 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 && make serve
```
> **CLI language support:** Use `aegis --lang zh` for Simplified Chinese (简体中文), or set `AEGIS_LANG=zh`.
**Installation alternatives:** See the [Installation Guide](https://lbedner.github.io/aegis-stack/installation/) for `uv tool install`, `pip install`, and development setup.
## Overseer - Your Application's Control Plane
[Live Demo: sector-7g.dev/dashboard](https://sector-7g.dev/dashboard/)
**[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** is the embedded control plane that ships with every Aegis Stack project.
It gives you full runtime visibility into your system - components, services, infrastructure, and data flows - through a single dashboard. No external tooling, no vendor integrations, no setup.
Inspect worker queues, scheduled jobs, database schema and migrations, AI token usage, auth sessions - everything your application is doing, in real time.
Every Aegis project ships with its own control plane 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.
```bash
# 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](https://lbedner.github.io/aegis-stack/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 / Dramatiq
**Services** (business logic)
- **Auth** → JWT authentication
- **AI** → PydanticAI / LangChain
- **Comms** → Resend + Twilio
[Components Docs →](https://lbedner.github.io/aegis-stack/components/) | [Services Docs →](https://lbedner.github.io/aegis-stack/services/)
## Learn More
- **[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** - Built-in system dashboard
- **[Deployment](https://lbedner.github.io/aegis-stack/deployment/)** - Deploy with backups, rollback, and health checks
- **[CLI Reference](https://lbedner.github.io/aegis-stack/cli-reference/)** - Complete command reference
- **[Evolving Your Stack](https://lbedner.github.io/aegis-stack/evolving-your-stack/)** - Add/remove components as needs change
- **[Technology Stack](https://lbedner.github.io/aegis-stack/technology/)** - Battle-tested technology choices
- **[About](https://lbedner.github.io/aegis-stack/about/)** - The philosophy and vision behind Aegis Stack
## 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.