aegra - Moses Yebei

Abstract

Open source alternative to LangGraph Platform (now LangSmith Deployments) - Self-hosted AI agent backend with FastAPI and PostgreSQL. Zero vendor lock-in, full control over your agent infrastructure.

The Problem

Running and managing LangGraph agents on an internal stack is difficult when the official LangSmith Deployments are locked into a cloud platform. Organizations need full control over persistence, authentication, and observability without vendor lock‑in.

What This Does

Aegra delivers a drop‑in replacement for LangSmith Deployments.

The FastAPI backend in libs/aegra-api/src/aegra_api/main.py exposes the same REST endpoints that the LangGraph SDK expects, so existing agents continue to work unchanged.
Database schema migrations live in libs/aegra-api/alembic/versions/…; the repo ships a PostgreSQL‑only persistence layer.
Custom authentication is wired through middleware in libs/aegra-api/src/aegra_api/core/auth_middleware.py, allowing JWT or other handlers to be plugged in.
Observation hooks in libs/aegra-api/src/aegra_api/observability/metrics.py expose Prometheus metrics, and the SSE framework in libs/aegra-api/src/aegra_api/core/sse.py implements Agent Protocol v2 streaming.

How It Is Wired

Entry point → FastAPI app

libs/aegra-api/src/aegra_api/main.py imports app_router from libs/aegra-api/src/aegra_api/api/ and mounts it on the FastAPI instance.
Each router module (assistants.py, threads.py, runs.py, …) registers routes that call service classes in libs/aegra-api/src/aegra_api/services/.

Service → ORM → Database

libs/aegra-api/src/aegra_api/services/assistant_service.py calls Assistant.create() from libs/aegra-api/src/aegra_api/models/assistants.py.
The model uses SQLAlchemy declarative mappings defined in libs/aegra-api/src/aegra_api/core/orm.py.
Calls ultimately hit the PostgreSQL session created in libs/aegra-api/src/aegra_api/core/database.py.

Observability & Streaming

libs/aegra-api/src/aegra_api/core/sse.py exposes a generator that yields SSE events.
libs/aegra-api/src/aegra_api/services/event_streaming/native_stream.py formats content‑block events for Agent Protocol v2.
Metrics are pushed from services/assistant_service.py through the metrics target in libs/aegra-api/src/aegra_api/observability/targets/.

Lifecycle

A run starts at the FastAPI route, enters the service layer, persists a Run record, triggers the executor (services/executor.py), and streams back via SSE.
The whole flow touches only main.py, the router, the service, the ORM, and the database: 5 distinct modules, with the router being the widest blast radius because it defines the API surface.

How To Use It

Setup

git clone https://github.com/moses-y/aegra
cd aegra
cp .env.example .env          # set OPENAI_API_KEY and other vars
uv sync                        # install deps (uv from pyproject.toml)

Configuration

Environment variables are listed in .env.example.
docker-compose.yml starts PostgreSQL and the FastAPI server; docker-compose.dev.yml adds a development overlay.

Running it

docker compose up

or via the CLI:

pip install aegra-cli
aegra init          # scaffolds a new project
cd <project>
cp .env.example .env
uv sync
uv run aegra dev    # starts dev server + DB

Calling the API

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":"Hi!"}]},
):
    print(chunk)

Real-World Use

A data‑science team can spin up an on‑premise Aegra instance, add custom JWT auth via auth_registry.py, and run LangGraph agents that ingest internal data pipelines. The same SDK code that talks to LangSmith now talks to http://<host>:2026.

Code Health & Issues

Low (Non‑reproducible builds) – libs/aegra-api/pyproject.toml declares dependencies without a lockfile.
233 test files – tests are present in tests/ and are run in CI.
CI – /.github/workflows/ci.yml runs unit tests and linting.
License – MIT, see LICENSE.

No critical security or linting failures were detected in the static analysis run.

The Bottom Line

Aegra is a solid, well‑structured self‑hosted alternative to LangSmith Deployments. It preserves API compatibility, offers full control over persistence and auth, and ships with streaming support out of the box. The code base is mature, with a clear separation of concerns, but the absence of a dependency lockfile means builds can drift. It is suitable for teams that need on‑premise control and are comfortable managing a PostgreSQL backend.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

485 files

Python389
Markdown14
YAML13
JSON6
TOML3

ReactDjangoDockerLangChain

Module dependencies

The 10 most depended-upon modules of 380, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_examples_cron_example_graph["graph"] n1_es_react_agent_hitl___init__["__init__"] n2_amples_cron_example___init__["__init__"] n3_les_react_agent_hitl_context["context"] n4_examples_cron_example_setup["setup"] n5_amples_custom_routes_example["custom_routes_example"] n6_examples_factory___init__["__init__"] n7_examples_factory_context["context"] n8_examples_factory_graph["graph"] n9_examples_factory_tools["tools"] n2_amples_cron_example___init__ --> n0_examples_cron_example_graph n3_les_react_agent_hitl_context --> n1_es_react_agent_hitl___init__

Dependencies

5 of 70 declared dependencies are a major version behind. Resolved 55 of 70 against the registry.

Package	Declared	Latest	Behind
`redis`	>=5.0.0	8.1.0	3 major
`rich`	>=13.0	15.0.0	2 major
`structlog`	>=25.4.0	26.1.0	1 major
`asgi-correlation-id`	>=4.3.4	5.0.1	1 major
`pytest-cov`	>=6.0.0	7.1.0	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds libs/aegra-api/pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

astral-sh/setup-uv@v4, codecov/codecov-action@v5, pypa/gh-action-pypi-publish@release/v1, ncipollo/release-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Replace the wildcard CORS origin with an explicit allow listhigh

libs/aegra-api/src/aegra_api/main.py

allow_origins=["*"]

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/release.yml

line 221 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

deployments/docker/Dockerfile

python:${PY_VERSION}-slim-bookworm

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/e2e.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.