{"id":30588659,"url":"https://github.com/lbedner/aegis-stack","last_synced_at":"2026-04-15T07:01:19.642Z","repository":{"id":307919931,"uuid":"973873346","full_name":"lbedner/aegis-stack","owner":"lbedner","description":"A production-ready FastAPI platform with modular components and a built-in control plane.","archived":false,"fork":false,"pushed_at":"2026-04-13T21:18:01.000Z","size":188634,"stargazers_count":99,"open_issues_count":92,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-13T23:15:56.165Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://lbedner.github.io/aegis-stack/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lbedner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-04-27T22:56:59.000Z","updated_at":"2026-04-13T21:17:43.000Z","dependencies_parsed_at":"2025-08-20T03:15:18.473Z","dependency_job_id":"199c5218-22a6-4131-8706-80a6cb35ba80","html_url":"https://github.com/lbedner/aegis-stack","commit_stats":null,"previous_names":["lbedner/aegis-stack"],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/lbedner/aegis-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbedner%2Faegis-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbedner%2Faegis-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbedner%2Faegis-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbedner%2Faegis-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lbedner","download_url":"https://codeload.github.com/lbedner/aegis-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbedner%2Faegis-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31830157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","boilerplate","cli","copier","copier-template","docker","fastapi","fastapi-starter","fastapi-template","langchain","llm","project-template","pydantic-ai","python","rag","scaffolding","starter-kit","uv"],"created_at":"2025-08-29T14:47:46.352Z","updated_at":"2026-04-15T07:01:19.580Z","avatar_url":"https://github.com/lbedner.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/aegis-manifesto-dark.png\"\u003e\n  \u003cimg src=\"docs/images/aegis-manifesto.png\" alt=\"Aegis Stack\" width=\"400\"\u003e\n\u003c/picture\u003e\n\n[![CI](https://github.com/lbedner/aegis-stack/workflows/CI/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/ci.yml)\n[![Documentation](https://github.com/lbedner/aegis-stack/workflows/Deploy%20Documentation/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/docs.yml)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)\n\n[![Monthly Downloads](https://img.shields.io/pypi/dm/aegis-stack)](https://pypi.org/project/aegis-stack/)\n[![Total Downloads](https://static.pepy.tech/badge/aegis-stack)](https://pepy.tech/project/aegis-stack)\n[![PyPI - Top 10% 2026](https://img.shields.io/badge/PyPI-Top_10%25_2026-2ea043)](https://clickpy.clickhouse.com/dashboard/aegis-stack?min_date=2026-01-01\u0026max_date=2026-12-31)\n\n[![Commits per Month](https://img.shields.io/github/commit-activity/m/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)\n[![Total Commits](https://img.shields.io/github/commit-activity/t/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)\n[![Last Commit](https://img.shields.io/github/last-commit/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)\n\nYou need to ship reliable software, but management only gave you 2 weeks.\n\nNo time for health checks, proper testing, or clean architecture. Just enough time for duct tape and hope.\n\n**What if you could go from idea to working prototype in the time it takes to grab coffee?**\n\n![Aegis Stack Quick Start Demo](docs/images/aegis-demo.gif)\n\nA production-ready FastAPI platform with modular components and a built-in control plane.\n\n## Prerequisites\n\n- **Python 3.11+**\n- **Docker \u0026 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.).\n\n## Quick Start\n\n```bash\n# Run instantly without installation\nuvx aegis-stack init my-api\n\n# Create with user authentication\nuvx aegis-stack init user-app --services auth\n\n# Create with background processing\nuvx aegis-stack init task-processor --components scheduler,worker\n\n# Start building\ncd my-api \u0026\u0026 make serve\n```\n\n\u003e **CLI language support:** Use `aegis --lang zh` for Simplified Chinese (简体中文), or set `AEGIS_LANG=zh`.\n\n**Installation alternatives:** See the [Installation Guide](https://lbedner.github.io/aegis-stack/installation/) for `uv tool install`, `pip install`, and development setup.\n\n## Overseer - Your Application's Control Plane\n\n![Overseer](docs/images/overseer-demo.gif)\n\n\u003csub\u003e[Live Demo: sector-7g.dev/dashboard](https://sector-7g.dev/dashboard/)\u003c/sub\u003e\n\n**[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** is the embedded control plane that ships with every Aegis Stack project.\n\nIt 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.\n\nInspect worker queues, scheduled jobs, database schema and migrations, AI token usage, auth sessions - everything your application is doing, in real time.\n\nEvery Aegis project ships with its own control plane from day one.\n\n## CLI - First-Class System Interface\n\n![CLI Demo](docs/images/cli-demo.gif)\n\nThe Aegis CLI is a first-class interface to your running system.\n\nIt goes beyond simple health checks, exposing rich, component-specific commands for inspecting and understanding your application from the terminal.\n\nQuery worker queues, scheduler activity, database state, AI usage, and service configuration, all without leaving the CLI.\n\nThe same system intelligence that powers Overseer and Illiana is available here, optimized for terminal workflows.\n\n## Illiana - Optional System Operator\n\n![Illiana Demo](docs/images/illiana-demo.gif)\n\nWhen the AI service is enabled, Aegis exposes an additional interface: **Illiana**.\n\nIlliana is a conversational interface that answers questions about your running system using live telemetry and optional RAG over your codebase.\n\nShe 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.\n\n## Your Stack Grows With You\n\n**Your choices aren't permanent.** Start with what you need today, add components when requirements change, remove what you outgrow.\n\n```bash\n# Monday: Ship MVP\naegis init my-api\n\n# Week 3: Add scheduled reports\naegis add scheduler --project-path ./my-api\n\n# Month 2: Need async workers\naegis add worker --project-path ./my-api\n\n# Month 6: Scheduler not needed\naegis remove scheduler --project-path ./my-api\n\n# Stay current with template improvements\naegis update\n```\n\n| Starter | Add Later? | Remove Later? | Git Conflicts? |\n|-----------|------------|---------------|----------------|\n| **Others** | ❌ Locked at init | ❌ Manual deletion | ⚠️ High risk |\n| **Aegis Stack** | ✅ One command | ✅ One command | ✅ Auto-handled |\n\n![Component Evolution Demo](docs/images/aegis-evolution-demo.gif)\n\nMost 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.\n\n## Available Components \u0026 Services\n\n**Components** (infrastructure)\n\n- **Core** → FastAPI + Pydantic V2 + Uvicorn\n- **Database** → Postgres / SQLite\n- **Cache/Queue** → Redis\n- **Scheduler** → APScheduler\n- **Worker** → Arq / Taskiq / Dramatiq\n\n**Services** (business logic)\n\n- **Auth** → JWT authentication\n- **AI** → PydanticAI / LangChain\n- **Comms** → Resend + Twilio\n\n[Components Docs →](https://lbedner.github.io/aegis-stack/components/) | [Services Docs →](https://lbedner.github.io/aegis-stack/services/)\n\n## Learn More\n\n- **[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** - Built-in system dashboard\n- **[Deployment](https://lbedner.github.io/aegis-stack/deployment/)** - Deploy with backups, rollback, and health checks\n- **[CLI Reference](https://lbedner.github.io/aegis-stack/cli-reference/)** - Complete command reference\n- **[Evolving Your Stack](https://lbedner.github.io/aegis-stack/evolving-your-stack/)** - Add/remove components as needs change\n- **[Technology Stack](https://lbedner.github.io/aegis-stack/technology/)** - Battle-tested technology choices\n- **[About](https://lbedner.github.io/aegis-stack/about/)** - The philosophy and vision behind Aegis Stack\n\n## For The Veterans\n\n![Ron Swanson](docs/images/ron-swanson.gif)\n\nNo reinventing the wheel. Just the tools you already know, pre-configured and ready to compose.\n\nAegis Stack respects your expertise. No custom abstractions or proprietary patterns to learn. Pick your components, get a production-ready foundation, and build your way.\n\nAegis gets out of your way so you can get started.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbedner%2Faegis-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flbedner%2Faegis-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbedner%2Faegis-stack/lists"}