aegis-stack 0.18.0

Inspired by the Neverwinter Nights toolset, Project Zero Dawn, and Dr. Wily.

Full-stack Python apps that know what they are.

Aegis Stack assembles a complete FastAPI system (API, workers, scheduler, database, auth, AI) and builds a typed map from its architecture, code, and live runtime (the Twin). That lets the system draw itself, explain itself, and catch changes that break its rules.

Build a private finance system, an agent that joins your meetings, an MCP server for your own tools, a local AI app on Ollama, or a voice-first internal assistant, and run it all from the same place.

An app. Build from a blueprint or pick your pieces. Add or remove them later; your changes are merged, not overwritten.

A server. One command, or one button in Overseer, provisions a server in your own Hetzner or DigitalOcean account, adds HTTPS, and deploys. The server, the bill, and the data stay yours.

A control plane. A live map of your system, from the whole stack down to a single function, with errors, deploys, jobs, resources, and cost on the same map. See Overseer.

An operator. Talk to Illiana or type. She reads that map, answers with diagrams instead of guesses, and reviews every pull request against the system's rules.

Quick Start

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.

# 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 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 and remove what you outgrow. Where a change touches files you've edited, your edits are merged in, and anything that can't merge cleanly is marked for you to review.

Components

Component	What you get
Backend	FastAPI on uvicorn or granian, lifecycle hooks, in-memory request metrics, API load testing for every route
CLI	Typer, first-class system interface
Frontend	Flet, ships with the Overseer system dashboard
Browser	Remote Chromium in its own container, driven over Playwright: JavaScript pages, sign-ins, a bot that joins a meeting
Database	Postgres (self-hosted or Neon serverless) or SQLite + SQLModel ORM
Deploy	Deployment target (Docker Compose), read by the Overseer
Inference	Local AI models via Ollama
Ingress	Traefik v3 reverse proxy with TLS
MCP	Serves the app's own tools to Claude Desktop, Claude Code or a local model over MCP: the tools you grant, never a write
Observability	Pydantic Logfire tracing + metrics + logging
Redis	Redis for caching, sessions, pub/sub
Scheduler	APScheduler with persistent jobs
Secrets	Encrypted credential store: keys set while the app runs, checked with the provider on paste, never shown again
Storage	S3 object storage for the files an app keeps, SeaweedFS in dev
Web Frontend	Server-rendered pages at /: Jinja2 + htmx + Alpine, Tailwind/DaisyUI styling
Worker	Pluggable Arq, Taskiq, or Dramatiq

Components Docs →

Services

Service	What you get
AI	Conversational agents, RAG, model catalog, TTS and STT (PydanticAI / LangChain across 7 providers)
Auth	Persistent sessions with refresh-token rotation, GitHub/Google sign-in, RBAC, multi-tenant Organizations
Blog	Markdown publishing with drafts, tags, and an Overseer editor
Comms	Transactional email (Resend) + SMS / voice (Twilio)
Documents	Content-addressed document store, deduped, with page-addressed extraction
Finance	Personal finance aggregation (accounts, transactions, net worth, import)
Insights	Adoption metrics across GitHub, PyPI, Plausible, Reddit
Meetings	A bot that joins Google Meet as its own agent: transcript, notes, threads, people, what keeps coming up, joined from its calendar
Payment	Stripe checkout, subscriptions, refunds, disputes
Research	Outside posts and threads, collected by saved searches

Services Docs →

Plugins

What the built-in services don't cover can come from a plugin: a Python package that adds routes, tables, a CLI and a dashboard card, and goes in and out the same way (aegis add <name>, aegis remove <name>). Browse them at aegis-stack.io/plugins or with aegis plugins search, and start your own with aegis plugins create.

Plugins Docs →

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
Provision	aegis deploy-provision rents a server on Hetzner or DigitalOcean (price shown first), names it, turns on HTTPS, and deploys. More providers to come
From Overseer	Overseer > Deployments: pick a size and region at its price, see whether the stack fits, then deploy, back up, roll back, or destroy from the page
Deploy CLI	One-command deploys to any VPS over SSH (rsync + Docker), no PaaS lock-in
Server Setup	aegis deploy-setup provisions Ubuntu, Debian, or Fedora boxes (Docker + firewall)
Backups & Rollback	pg_dump before every deploy, retention policy, automatic rollback on failed health checks
TLS / HTTPS	Let's Encrypt via the Traefik ingress component, zero config when a domain is set

Deployment Docs →

Not a Starter Template

Your choices aren't permanent. Start with what you need today, add 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

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

Overseer - Your Application's Control Plane

_{Live Demo: sector-7g.dev/dashboard}

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 - Package analytics with honest decomposition (Total / Filtered / Human)
• Sector 7G - Live demo: millions of tasks on a single $5 VPS, zero restarts
• NWVault Revival - Searchable archive of the original Neverwinter Vault (2002-2014), built in 24 hours

Learn More

• Overseer - Built-in system dashboard
• Deployment - Deploy with backups, rollback, and health checks
• Plugins - Extend a project with third-party packages, or write your own
• CLI Reference - Complete command reference
• Evolving Your Stack - Add/remove components as needs change
• Technology Stack - Battle-tested technology choices
• 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.