Skip to main content

​
Using the CLI

The CLI is the recommended way to create and manage Aegra projects. 
pip install aegra-cli
Then initialize a new project: 
aegra init
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: 
git clone https://github.com/ibbybuilds/aegra.git
cd aegra
cp .env.example .env
# Add your OPENAI_API_KEY to .env
Install dependencies and start the development server: 
uv sync --all-packages
uv run aegra dev
Or start with Docker Compose: 
docker compose up

​
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 and aegra up work on Windows. However, aegra serve (production mode without Docker) is not supported on Windows because psycopg requires SelectorEventLoop while Windows defaults to ProactorEventLoop. For production deployments, use Docker or a Linux server.

​
Project structure

After aegra init, your project looks like this: 
my-project/
├── aegra.json           # Graph and server configuration
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── graph.py     # Your LangGraph agent
│       ├── state.py     # State and input schemas
│       ├── context.py   # Runtime context
│       ├── prompts.py   # System prompts
│       └── utils.py     # Helper functions
├── .env.example         # Environment variable template
├── .gitignore
├── Dockerfile           # Container build config
├── docker-compose.yml   # Local development stack
├── pyproject.toml       # Python dependencies
└── README.md

​
Verify the installation

Start the server and check the health endpoint: 
uv run aegra dev
In another terminal: 
curl http://localhost:2026/health
You should see: 
{"status": "healthy"}
Visit http://localhost:2026/docs for the interactive API documentation.