Using the CLI
The CLI is the recommended way to create and manage Aegra projects.
Then initialize a new project:
The CLI prompts you for a location, a template (simple-chatbot or react-agent), and a project name. It generates the project structure, aegra.json, Dockerfile, docker-compose.yml, and .env.example.
Install aegra-cli directly — not the aegra meta-package on PyPI. The aegra package is a convenience wrapper that does not support version pinning.
From source
Clone the repository and run directly:
Install dependencies and start the development server:
Or start with Docker Compose:
Requirements
Python
Aegra requires Python 3.12+ for both the API server and the CLI.
PostgreSQL
Aegra uses PostgreSQL with the pgvector extension for persistence and vector search. The recommended image is pgvector/pgvector:pg18.
When you use aegra dev or aegra up, PostgreSQL is started automatically via Docker. For aegra serve, you provide your own database via DATABASE_URL or POSTGRES_* environment variables.
Docker
Docker is required for local development (aegra dev starts a PostgreSQL container). For production, you can either run everything in Docker (aegra up) or provide an external database and run with aegra serve.
Windows
aegra dev, aegra up, and aegra serve work on Windows. The CLI passes uvicorn a SelectorEventLoop factory on Windows, since psycopg cannot connect on the ProactorEventLoop that uvicorn otherwise defaults to without --reload. For production deployments we still recommend Docker or a Linux server.
Project structure
After aegra init, your project looks like this:
Verify the installation
Start the server and check the health endpoint:
In another terminal:
You should see:
Visit http://localhost:2026/docs for the interactive API documentation.
