Aegra

Self-hosted LangSmith Deployments alternative. Your infrastructure, your rules.

Aegra is a drop-in replacement for LangSmith Deployments. Use the same LangGraph SDK, same APIs, but run it on your own infrastructure with PostgreSQL persistence.

Works with: Agent Chat UI | LangGraph Studio | AG-UI / CopilotKit

🆕 New: Agent Protocol v2 streaming. Thread-scoped SSE with content-block events, per-subgraph lifecycle, and native human-in-the-loop resume — the wire the latest LangGraph SDKs and useStream() target. Enabled by default. See the streaming guide.

🚀 Quick Start

Using the CLI (Recommended)

Prerequisites: Python 3.12+, Docker (for PostgreSQL)

pip install aegra-cli
Initialize a new project — prompts for location, template, and name
aegra init
Follow the printed next steps:
cd <your-project>
cp .env.example .env     # Add your OPENAI_API_KEY to .env
uv sync                  # Install dependencies
uv run aegra dev         # Start PostgreSQL + dev server

Note: Always install aegra-cli directly — not the aegra meta-package. The aegra package on PyPI is a convenience wrapper that does not support version pinning.

From Source

git clone https://github.com/aegra/aegra.git
cd aegra
cp .env.example .env
Add your OPENAI_API_KEY to .env
docker compose up

Open http://localhost:2026/docs to explore the API.

Your existing LangGraph code works without changes:

from langgraph_sdk import get_client
client = get_client(url="http://localhost:2026")
assistant = await client.assistants.create(graph_id="agent")
thread = await client.threads.create()
async for chunk in client.runs.stream(
    thread_id=thread["thread_id"],
    assistant_id=assistant["assistant_id"],
    input={"messages": [{"type": "human", "content": "Hello!"}]},
):
    print(chunk)

🔥 Why Aegra?

Based on LangChain pricing as of February 2026. An enterprise tier with self-hosting is also available at custom pricing.

| | LangSmith Deployments | Aegra | |:--|:--|:--| | Deploy agents | Local dev only (Free), paid cloud (Plus) | Free, unlimited | | Custom auth | Not available (Free), available (Plus) | Python handlers (JWT/OAuth/Firebase) | | Scheduled cron jobs | Not available (Free), available (Plus) | Built-in, free | | Self-hosted | Enterprise only (license key required) | Always (Apache 2.0) | | Own database | Managed only (Free/Plus), bring your own (Enterprise) | Bring your own Postgres | | Tracing | LangSmith only | Any OTLP backend (Langfuse, Phoenix, etc.) | | Data residency | LangChain cloud (Free/Plus), your infrastructure (Enterprise) | Your infrastructure | | SDK | LangGraph SDK | Same LangGraph SDK |

✨ Features

• Agent Protocol compliant - Works with Agent Chat UI, LangGraph Studio, CopilotKit
• Worker architecture - Redis job queue with 30 concurrent runs per instance, lease-based crash recovery, and horizontal scaling across multiple instances
• Scheduled cron jobs - Trigger runs on a schedule with standard 5-field or seconds-level 6-field expressions, IANA timezone support, and multi-instance safe SKIP LOCKED claim
• Human-in-the-loop - Approval gates and user intervention points
• Streaming - Real-time SSE streaming with cross-instance pub/sub and automatic reconnection with event replay. Supports both the legacy run-scoped stream and Agent Protocol v2 thread-scoped streaming (content-block events, per-subgraph lifecycle, HITL resume) for the latest LangGraph SDKs and useStream()
• Persistent state - PostgreSQL checkpoints via LangGraph
• Configurable auth - JWT, OAuth, Firebase, or none
• Unified Observability - Fan-out tracing support via OpenTelemetry
• Semantic store - Vector embeddings with pgvector
• Custom routes - Add your own FastAPI endpoints

🛠️ CLI Commands

aegra init              # Interactive — asks for location, template, and name
aegra init ./my-agent   # Create at path (still prompts for template)
aegra dev               # Start development server (hot reload + auto PostgreSQL)
aegra serve             # Start production server (no reload)
aegra up                # Build and start all Docker services
aegra down              # Stop Docker services
aegra version           # Show version info

📚 Documentation

docs.aegra.dev — Full documentation with guides, API reference, and configuration.

| Topic | Description | |-------|-------------| | Quickstart | Get a running server in under 5 minutes | | Configuration | aegra.json format and all options | | Authentication | JWT, OAuth, Firebase, or custom auth handlers | | Worker Architecture | Redis job queue, crash recovery, horizontal scaling | | Scheduled cron jobs | Trigger runs on a schedule with timezone support and multi-instance safe claim | | Streaming | 8 SSE stream modes with reconnection | | Store | Key-value and semantic search storage | | Observability | Fan-out tracing to Langfuse, Phoenix, or any OTLP backend | | Deployment | Docker, PaaS, and Kubernetes deployment | | Migration | Migrate from LangSmith Deployments |

💬 Community & Support

• Discord - Chat with the community
• GitHub Discussions - Ask questions, share ideas
• GitHub Issues - Report bugs

🏗️ Built With

• FastAPI - HTTP layer
• LangGraph - State management & graph execution
• PostgreSQL - Persistence & checkpoints
• Redis - Job queue, SSE pub/sub, crash recovery
• OpenTelemetry - Observability standard
• pgvector - Vector embeddings

🤝 Contributing

We welcome contributions! See Contributing guide and check out good first issues.

💖 Support the Project

The best contribution is code, PRs, and bug reports - that's what makes open source thrive.

For those who want to support Aegra financially, whether you're using it in production or just believe in what we're building, you can become a sponsor. Sponsorships help keep development active and the project healthy.

📄 License

Apache 2.0 - see LICENSE.

⭐ Star us if Aegra helps you escape vendor lock-in ⭐