[](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://github.com/lbedner/aegis-stack/commits) [](https://github.com/lbedner/aegis-stack/commits) [](https://github.com/lbedner/aegis-stack/commits) **Aegis Stack is an open-source CLI that scaffolds production-ready FastAPI applications and lets you add, remove, and update components and services on existing projects without rewrites.** 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?**  **Ship FastAPI apps that grow with you.** Aegis Stack scaffolds complete FastAPI applications with auth, payments, workers, AI, and a built-in control plane. Add what you need, remove what you don't, update when the framework improves. ## Quick Start ```bash uvx aegis-stack init my-api ``` `init` opens a full-screen guided setup that walks through every component and service with explanations. Prefer the classic one-line prompts? Pass `--quick`.

More examples

```bash # Skip the guided setup, use the classic one-line prompts uvx aegis-stack init my-api --quick # Add user authentication out of the box uvx aegis-stack init user-app --services auth # Add background processing + scheduling uvx aegis-stack init task-processor --components scheduler,worker # Everything wired up at init uvx aegis-stack init full-app --services auth,payment,comms --components worker,scheduler ```

> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Run e.g. `uvx aegis-stack --lang zh init my-api`, or set `AEGIS_LANG=zh`. **Installation alternatives:** See the [Installation Guide](https://docs.aegis-stack.io/installation/) for `uv tool install`, `pip install`, and development setup. ## Customizing Your Stack  **Components** are infrastructure pieces (database, workers, scheduler, cache). **Services** are business capabilities (auth, AI, payments, comms). **Don't worry about what you pick today.** Add anything later with a single command, remove what you outgrow, no rework required. ### Components | Component | What you get | | |---|---|---| | **[Backend](https://docs.aegis-stack.io/components/backend/)** | FastAPI + lifecycle hooks, in-memory request metrics, API load testing for every route |  | | **[CLI](https://docs.aegis-stack.io/cli-reference/)** | Typer, first-class system interface |  | | **[Frontend](https://docs.aegis-stack.io/components/frontend/)** | Flet, ships with the Overseer system dashboard |  | | **[Web Frontend](https://docs.aegis-stack.io/components/web-frontend/)** | Server-rendered pages at `/`: Jinja2 + htmx + Alpine, Tailwind/DaisyUI styling |  | | **[Cache](https://docs.aegis-stack.io/components/)** | Redis for caching, sessions, pub/sub |  | | **[Database](https://docs.aegis-stack.io/components/database/)** | Postgres (self-hosted or Neon serverless) or SQLite + SQLModel ORM |  | | **[Inference](https://docs.aegis-stack.io/components/)** | Local AI models via Ollama |  | | **[Ingress](https://docs.aegis-stack.io/components/ingress/)** | Traefik v3 reverse proxy with TLS |  | | **[Observability](https://docs.aegis-stack.io/components/observability/)** | Pydantic Logfire tracing + metrics + logging |  | | **[Scheduler](https://docs.aegis-stack.io/components/scheduler/)** | APScheduler with persistent jobs |  | | **[Worker](https://docs.aegis-stack.io/components/worker/)** | Pluggable Arq, Taskiq, or Dramatiq |  | [Components Docs →](https://docs.aegis-stack.io/components/) ### Services | Service | What you get | | |---|---|---| | **[AI](https://docs.aegis-stack.io/services/ai/)** | Conversational agents, RAG, model catalog, TTS and STT (PydanticAI / LangChain across 7 providers) |  | | **[Auth](https://docs.aegis-stack.io/services/auth/)** | Persistent sessions with refresh-token rotation, GitHub/Google sign-in, RBAC, multi-tenant Organizations |  | | **[Blog](https://docs.aegis-stack.io/services/blog/)** | Markdown publishing with drafts, tags, and an Overseer editor |  | | **[Comms](https://docs.aegis-stack.io/services/comms/)** | Transactional email (Resend) + SMS / voice (Twilio) |  | | **[Insights](https://docs.aegis-stack.io/services/insights/)** | Adoption metrics across GitHub, PyPI, Plausible, Reddit |  | | **[Payments](https://docs.aegis-stack.io/services/payment/)** | Stripe checkout, subscriptions, refunds, disputes |  | [Services Docs →](https://docs.aegis-stack.io/services/) ## Integrations Aegis Stack is the orchestration layer. Services and components wire into best-in-class tools you already trust, so you keep your vendor choices and your data. ## CI/CD for Your Stack Every generated project ships with GitHub Actions and developer tooling pre-wired, so the first push to GitHub runs checks automatically, and one command wires up continuous deployment to your server.

Capability	What you get	Status
CI Workflow	Lint, type checking, and tests on every push and PR (parallel jobs, cached)
Code Scanning	CodeQL static analysis on every PR and on a weekly schedule
Pre-commit	Ruff, ruff-format, and type-check hooks (opt-in)
Continuous Deploy	Generates a dedicated SSH deploy key, installs it on your server, pushes secrets to GitHub, and scaffolds a deploy workflow (manual trigger by default)

## Deploying Your Stack | Capability | What you get | | |---|---|---| | **[Deploy CLI](https://docs.aegis-stack.io/deployment/)** | One-command deploys to any VPS over SSH (rsync + Docker), no PaaS lock-in |  | | **[Server Setup](https://docs.aegis-stack.io/deployment/#aegis-deploy-setup)** | `aegis deploy-setup` provisions Ubuntu, Debian, or Fedora boxes (Docker + firewall) |  | | **[Backups & Rollback](https://docs.aegis-stack.io/deployment/#backup-and-rollback)** | `pg_dump` before every deploy, retention policy, automatic rollback on failed health checks |  | | **[TLS / HTTPS](https://docs.aegis-stack.io/deployment/#tlshttps-with-lets-encrypt)** | Let's Encrypt via the Traefik ingress component, zero config when a domain is set |  | [Deployment Docs →](https://docs.aegis-stack.io/deployment/) ## Your Stack Grows With You **Your choices aren't permanent.** Start with what you need today, add 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://docs.aegis-stack.io/evolving-your-stack/)** for the complete guide. ## Overseer - Your Application's Control Plane _{[Live Demo: sector-7g.dev/dashboard](https://sector-7g.dev/dashboard/)} **[Overseer](https://docs.aegis-stack.io/overseer/)** is the embedded control plane that ships with every Aegis Stack project. - Live health of every component and service in one view - Worker queues, scheduled jobs, recent runs - Database schema, tables, and migration state - AI token usage and conversation history - Auth sessions and user activity - No external tooling, no vendor integrations, no setup ## CLI - First-Class System Interface The Aegis CLI is a first-class interface to your running system. Not just a health check, but a full inspection layer. - Component-aware commands for every running subsystem - Inspect worker queues, scheduler runs, database state - Query AI usage, auth sessions, service configuration - Same data Overseer sees, terminal-native - Built into every generated project, no extra installs ## Illiana - Optional System Operator When the AI service is enabled, Aegis exposes an additional interface: **Illiana**, a conversational operator over your running system. - Ask questions in plain language about live system state - Backed by live telemetry from Overseer and the CLI - Optional RAG over your codebase for code-aware answers - Opt-in: only available when the AI service is on - Nothing in the stack depends on her being there ## Powered By Aegis Stack - **[Aegis Pulse](https://pulse.aegis-stack.io/)** - Package analytics with honest decomposition (Total / Filtered / Human) - **[Sector 7G](https://sector-7g.dev/dashboard/)** - Live demo: millions of tasks on a single $5 VPS, zero restarts - **[NWVault Revival](https://167.99.48.44/)** - Searchable archive of the original Neverwinter Vault (2002-2014), built in 24 hours ## Learn More - **[Overseer](https://docs.aegis-stack.io/overseer/)** - Built-in system dashboard - **[Deployment](https://docs.aegis-stack.io/deployment/)** - Deploy with backups, rollback, and health checks - **[CLI Reference](https://docs.aegis-stack.io/cli-reference/)** - Complete command reference - **[Evolving Your Stack](https://docs.aegis-stack.io/evolving-your-stack/)** - Add/remove components as needs change - **[Technology Stack](https://docs.aegis-stack.io/technology/)** - Battle-tested technology choices - **[About](https://docs.aegis-stack.io/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.