> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aegra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> All the ways to install and run Aegra.

## Using the CLI

The CLI is the recommended way to create and manage Aegra projects.

```bash theme={null}
pip install aegra-cli
```

Then initialize a new project:

```bash theme={null}
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`.

<Warning>
  Install `aegra-cli` directly — not the `aegra` meta-package on PyPI. The `aegra` package is a convenience wrapper that does not support version pinning.
</Warning>

## From source

Clone the repository and run directly:

```bash theme={null}
git clone https://github.com/aegra/aegra.git
cd aegra
cp .env.example .env
# Add your OPENAI_API_KEY to .env
```

Install dependencies and start the development server:

```bash theme={null}
uv sync --all-packages
uv run aegra dev
```

Or start with Docker Compose:

```bash theme={null}
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:

```bash theme={null}
uv run aegra dev
```

In another terminal:

```bash theme={null}
curl http://localhost:2026/health
```

You should see:

```json theme={null}
{"status": "healthy"}
```

Visit [http://localhost:2026/docs](http://localhost:2026/docs) for the interactive API documentation.