upstreamyard/aegra repository overview

⁠Aegra container image

Multi-arch (amd64, arm64), signed container images for Aegra⁠, the open-source, self-hosted alternative to LangGraph Platform.

Tags: latest, <major>.<minor> (e.g. 0.10), <version> (e.g. 0.10.8, matching the Aegra releases⁠). New Aegra releases are built automatically within 24 hours.

⁠At a glance

AI agents and coding assistants: read AGENTS.md⁠ for deployment rules, and llms.txt⁠ for an index of all docs.

⁠Quick start

Aegra needs PostgreSQL with the pgvector⁠ extension; the pgvector/pgvector:pg18 image is Postgres 18 with pgvector included (Aegra requirement⁠). Redis is optional and only needed when you run several replicas.

curl -O https://raw.githubusercontent.com/upstreamyard/aegra/main/docker-compose.yml
export OPENAI_API_KEY=sk-...
docker compose up -d
curl http://localhost:2026/ready

Or with plain docker run:

docker run -d -p 2026:2026 \
  -e DATABASE_URL=postgresql://user:password@your-postgres:5432/aegra \
  -e OPENAI_API_KEY=sk-... \
  upstreamyard/aegra:latest

Point any LangGraph SDK client at http://localhost:2026.

⁠Running your own agents

Aegra runs your agent code. The image provides the server and its dependencies; you add a folder with your files:

my-agents/
├── aegra.json      # which graphs to serve (and optionally which auth handler)
├── graph.py        # your LangGraph graph(s)
└── my_auth.py      # optional: authentication handler

{
  "graphs": { "agent": "./graph.py:graph" },
  "auth": { "path": "./my_auth.py:auth" }
}

Paths in aegra.json are relative to the folder containing aegra.json.

⁠Option 1: mount your files (no build)

Works when your code only uses packages that are already in the image. This is best for development, since you can edit files and restart without rebuilding.

docker run -d -p 2026:2026 \
  -e DATABASE_URL=postgresql://user:password@your-postgres:5432/aegra \
  -e AEGRA_CONFIG=/app/agents/aegra.json \
  -v ./my-agents:/app/agents:ro \
  upstreamyard/aegra:0.10

With Docker Compose, add the same AEGRA_CONFIG variable and a volumes: ["./my-agents:/app/agents:ro"] entry to the aegra service. The Helm chart can't mount files yet, so on Kubernetes use option 2.

⁠Option 2: build your own image on top (recommended for production)

Needed when your code uses extra Python packages, e.g. for Salesforce or Microsoft Teams, and the usual way to ship agents to Kubernetes:

FROM upstreamyard/aegra:0.10
USER root
RUN pip install --no-cache-dir simple-salesforce msgraph-sdk
USER 10001:10001
COPY my-agents/ /app/agents/
ENV AEGRA_CONFIG=/app/agents/aegra.json

docker build -t registry.example.com/my-agents:1.0 .
docker push registry.example.com/my-agents:1.0

Pinning 0.10 gets you Aegra's patch releases (and our image fixes) whenever you rebuild. With the Helm chart⁠, deploy it with --set image.repository=registry.example.com/my-agents --set image.tag=1.0.

⁠Credentials and settings

Never put API keys or passwords into the image. Pass them as environment variables when the container starts, and read them in your code with os.environ["SALESFORCE_TOKEN"]:

• docker run: -e SALESFORCE_TOKEN=... or --env-file .env
• Docker Compose: environment: or env_file:
• Helm chart: extraEnv for plain values, extraEnvFrom for a Kubernetes Secret:

extraEnvFrom:
  - secretRef:
      name: salesforce-credentials   # kubectl create secret generic salesforce-credentials --from-literal=SALESFORCE_TOKEN=...

⁠Configuration

All of Aegra's settings are environment variables. See the Aegra project's .env.example⁠ for the full list. The most important ones:

⁠Kubernetes

The recommended way is the Helm chart (upstreamyard/helm-charts⁠). It runs migrations as a Helm pre-install/pre-upgrade Job before pods start, which is the approach Aegra's docs recommend:

helm repo add upstreamyard https://upstreamyard.github.io/helm-charts
helm install aegra upstreamyard/aegra --set database.url='postgresql://user:password@host:5432/aegra'

Without Helm, examples/kubernetes/aegra.yaml⁠ is a plain-manifest starting point (Secret, migration Job, Deployment with probes, Service).

For more than one replica (the chart does all of this for you):

1. Run migrations once per release as a Job: command: ["aegra", "db", "upgrade"].
2. Set RUN_MIGRATIONS_ON_STARTUP=false, REDIS_BROKER_ENABLED=true and REDIS_URL on the Deployment.
3. Use /live for liveness and startup probes and /ready for readiness. Avoid /health for liveness: it fails when the database is down, and Kubernetes would then restart pods that are fine.

The container runs as non-root UID 10001 and is compatible with runAsNonRoot: true.

⁠Verifying images

Images are signed keylessly with cosign⁠ and include an SBOM and SLSA provenance:

cosign verify upstreamyard/aegra:latest \
  --certificate-identity-regexp '^https://github.com/upstreamyard/aegra/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

docker buildx imagetools inspect upstreamyard/aegra:latest --format '{{ json .SBOM }}'

⁠How it's built

.github/workflows/build.yml⁠ checks out the Aegra release tag and builds Dockerfile⁠. Before publishing, it starts the image against a real PostgreSQL and waits for /health to pass. Everything is public and reproducible.

Differences from the Aegra project's own deployments/docker/Dockerfile: the aegra CLI is installed (so the default aegra serve command works), tini runs as PID 1, there's a built-in HEALTHCHECK, the UID is fixed, and builds are multi-arch.

⁠Support

Issues with the image: open an issue here⁠. Issues with Aegra itself: aegra/aegra⁠.