Aegra

Overview

Aegra is an open-source agent server that implements the LangGraph Agent Server API: assistants, threads, background runs, streaming, the store and crons for the LangGraph agents in your image. This template runs your agent image on a bundled PostgreSQL with pgvector, which holds threads, runs, checkpoints and the store, and a bundled single-node Redis for the job queue and run event streams. It works with the LangGraph SDK and with frontends such as Agent Chat UI.

This template does not create a GVC. It deploys into an existing GVC that you already have, and that GVC should have exactly one location, because the bundled database and Redis run in one location.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-aegra`	Aegra API and background workers (standard, 1 replica by default, up to 10) on port `2026`	—
Identity	`RELEASE_NAME-aegra-identity`	Workload identity for Aegra	—
Policy	`RELEASE_NAME-aegra-policy`	Grants the identity `reveal` on exactly the secrets you name	—
Workload	`RELEASE_NAME-postgres`	PostgreSQL with pgvector (stateful, 1 replica)	`postgres.enabled: true` (default)
Volume set	`RELEASE_NAME-pg-vs`	PostgreSQL data volume	`postgres.enabled: true` (default)
Identity	`RELEASE_NAME-pg-identity`	Workload identity for PostgreSQL	`postgres.enabled: true` (default)
Policy	`RELEASE_NAME-pg-policy`	Grants the PostgreSQL identity `reveal` on the database credentials secret	`postgres.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL (stateful, 3 replicas by default)	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-etcd`	etcd cluster for Patroni	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy endpoint that always points at the PostgreSQL leader	`postgresHA.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`	PostgreSQL data volume, one per replica	`postgresHA.enabled: true`
Volume set	`RELEASE_NAME-etcd-vs`	etcd data volume	`postgresHA.enabled: true`
Identity	`RELEASE_NAME-postgres-ha-identity`	Workload identity for Patroni PostgreSQL	`postgresHA.enabled: true`
Policy	`RELEASE_NAME-postgres-ha-policy`	Grants the Patroni identity `reveal` on its startup secrets and the database credentials secret	`postgresHA.enabled: true`
Identity	`RELEASE_NAME-etcd-identity`	Workload identity for etcd	`postgresHA.enabled: true`
Policy	`RELEASE_NAME-etcd-policy`	Grants the etcd identity `reveal` on its startup secret	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-patroni-startup`	Patroni startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-etcd-startup`	etcd startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-postgres-proxy-startup`	HAProxy startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-wal-g-backup-script`	Backup script used when backups are enabled	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-redis`	Redis job queue and run event streams (single node)	—
Identity	`RELEASE_NAME-redis-identity`	Workload identity for Redis	—
Policy	`RELEASE_NAME-redis-policy`	Grants the Redis identity access to its configuration secret	—
Secret	`RELEASE_NAME-redis-config`	Redis configuration	—

The template creates no credentials. The API is reachable only from inside the GVC until you set publicAccess.enabled: true.

Prerequisites

Create the database credentials secret

The bundled PostgreSQL initializes with this dictionary secret and Aegra connects with it. It holds exactly three keys: username and database (letters, digits and _) and password (any characters):

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=aegra \
  --entry password="$(openssl rand -hex 32)" \
  --entry database=aegra

Set postgres.config.credentialsSecretName to this name (or postgresHA.config.credentialsSecretName when you use the HA database). Secret names are org-wide, so give each release its own secret.

Create the optional secrets

Each is a dictionary secret created the same way. Agent secrets hold any keys your agent reads, such as OPENAI_API_KEY. Langfuse tracing needs the keys publicKey and secretKey. A Redis password needs the key password, URL-safe (letters, digits, -, _, .). See Agent secrets, Langfuse tracing and Redis.

Choose your agent image

The default image runs Aegra’s example agents. To serve your own graphs, build an image as described in Bring Your Own Agent.

Every secret your release names must exist before you install. If one does not, the deployment waits silently: cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message in cpln workload get-deployments RELEASE_NAME-aegra --gvc GVC_NAME -o yaml. Create the secret and the deployment recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-aegra --gvc GVC_NAME to skip the wait.

Optional database backups need a bucket and a Control Plane cloud account; see Backing Up.

Installation

The only required value is the name of the database credentials secret from Prerequisites:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/aegra \
  --version 1.0.0 --gvc GVC_NAME \
  --set postgres.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

To install with the highly available database, add

--set postgres.enabled=false --set postgresHA.enabled=true --set postgresHA.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

. To install with the CLI, UI, Terraform or Pulumi, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

aegra:
  image: upstreamyard/aegra:0.11.0   # your agent image (see Bring Your Own Agent)
  # set aegra.replicas: 2 and postgresHA.enabled: true for near-zero-downtime upgrades and failover
  replicas: 1                   # 1-10
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  requestTimeoutSeconds: 600    # longest /runs/wait or /runs/stream request on the public URL before it is cut (1-3600)
  extraEnv: []                  # plain settings, e.g. [{name: LOG_LEVEL, value: DEBUG}]

Agent secrets

agentSecrets:
  secretName: ""                # e.g. my-aegra-agent-secrets
  keys: []                      # each listed key becomes an env var, e.g. [OPENAI_API_KEY]

Access

publicAccess:
  enabled: false                # true = public *.cpln.app URL. Aegra has NO auth unless your image adds a handler
internalAccess:
  type: same-gvc                # none | same-gvc | same-org | workload-list
  workloads: []                 # used only with workload-list

Langfuse tracing

langfuse:
  secretName: ""                # dictionary with publicKey and secretKey; "" = tracing off
  baseUrl: http://my-langfuse-langfuse-web.my-gvc.cpln.local:3000   # or https://cloud.langfuse.com

Database

postgres:                       # every knob of the postgres template
  enabled: true
  image: pgvector/pgvector:0.8.7-pg18
  config:
    credentialsSecretName: my-aegra-db-credentials   # REQUIRED, create before install
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10                # GiB (minimum 10)
  backup:                       # scheduled backups to object storage (postgres template)
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *"       # daily at 2am UTC
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws               # aws, gcp or minio
    aws:
      bucket: my-aegra-backup-bucket
      region: us-east-1
      cloudAccountName: my-aegra-backup-cloudaccount
      policyName: my-aegra-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-aegra-backup-bucket
      cloudAccountName: my-aegra-backup-cloudaccount
      prefix: postgres/backups
    minio:                      # any S3-compatible endpoint
      endpoint: http://my-minio-workload:9000
      bucket: my-aegra-backup-bucket
      credentialsSecretName: my-aegra-minio-credentials   # dictionary: accessKey, secretKey
      prefix: postgres/backups

postgresHA:                     # every knob of the postgres-highly-available template
  enabled: false                # enable exactly one of postgres / postgresHA
  image: controlplanecorporation/patroni-postgres:0.8
  config:
    credentialsSecretName: my-aegra-db-credentials
  replicas: 3
  resources:                    # per Patroni replica
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi
  volumeset:
    capacity: 10                # GiB per replica (minimum 10)
  backup:                       # provider, aws, gcp, minio: same keys and defaults as postgres.backup
    enabled: false
    mode: logical               # logical or wal-g
    resources:
      cpu: 100m
      memory: 512Mi             # 128Mi OOM-kills wal-g mid-backup
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *"     # daily at 2am UTC
    walg:
      intervalSeconds: 21600    # every 6 hours

Redis

redis:
  mode: dev                     # required: one node; Aegra cannot use Sentinel
  redis:
    image: redis:8
    resources:
      maxCpu: 200m
      maxMemory: 256Mi
      minCpu: 80m
      minMemory: 128Mi
    auth:
      fromSecret:
        enabled: false          # true = Redis requires the password in the secret below
        name: ""                # e.g. my-aegra-redis
        passwordKey: password

Bring Your Own Agent

The default image is a community build of Aegra 0.11.0 with Aegra’s example agents: the graph stress_test runs with no model key, and agent needs OPENAI_API_KEY in the agent secrets. To serve your own graphs, build an image from it with your code and an aegra.json:

FROM upstreamyard/aegra:0.11.0
USER root
COPY requirements.txt /app/agents/requirements.txt
RUN pip install --no-cache-dir -r /app/agents/requirements.txt
COPY . /app/agents
USER 10001
ENV AEGRA_CONFIG=/app/agents/aegra.json

{
  "dependencies": ["."],
  "graphs": { "my_agent": "./my_agent/graph.py:graph" }
}

Build and push the image to your org’s private registry, then set aegra.image to the pushed image, for example ORG_NAME.registry.cpln.io/my-agent:1:

cpln image build --name my-agent:1 --dockerfile Dockerfile --push

Only your graphs are served; the example agents of the default image are not registered. Each graph is listed in /assistants/search with a generated id, and its graph_id is the name you listed in aegra.json. Run it by passing that name as "assistant_id": "my_agent".

Connecting

What	Address	Notes
Internal API	`http://RELEASE_NAME-aegra.GVC_NAME.cpln.local:2026`	Reachable per `internalAccess`
From your machine	`cpln port-forward RELEASE_NAME-aegra 2026:2026 --gvc GVC_NAME`, then `http://localhost:2026`	Works with the public URL off
Public URL	`status.canonicalEndpoint` of `cpln workload get RELEASE_NAME-aegra --gvc GVC_NAME -o yaml`	Only with `publicAccess.enabled: true`; has no authentication unless your image adds a handler
API reference	`/docs` on any of the addresses above	Interactive OpenAPI page

Point the LangGraph SDK (langgraph_sdk.get_client(url=...)) at the URL and use the graph name as the assistant id. To check the server, forward the port and read its version:

cpln port-forward RELEASE_NAME-aegra 2026:2026 --gvc GVC_NAME
curl http://localhost:2026/info

Chat With an Agent in a Browser

Aegra has no UI of its own. To chat with an agent, open the hosted Agent Chat UI with your public URL and a graph name:

https://agentchat.vercel.app/?apiUrl=PUBLIC_URL&assistantId=stress_test

The browser calls Aegra directly, so this needs publicAccess.enabled: true. Anyone with the public URL can call your agents unless your image adds an auth handler.

Operations

Backing Up

All state lives in PostgreSQL, so backing up the database backs up every thread, run, checkpoint and store entry. Enable postgres.backup.enabled (or postgresHA.backup.enabled with the HA database) and fill in the provider block. The bucket, cloud account and IAM policy are set up as described in the postgres or postgres-highly-available template, and a MinIO provider needs a dictionary secret with the keys accessKey and secretKey. Restore steps are in those templates’ pages.

Scaling and Availability

Aegra replicas share PostgreSQL and Redis, so they are interchangeable. Set aegra.replicas up to 10 to spread background runs across them. A run on a replica that stops or hangs is picked up again by a live replica and retried from its last checkpoint; Aegra does not drain runs on shutdown. For near-zero-downtime upgrades and failover, set aegra.replicas: 2 and enable postgresHA. Redis stays a single node, because Aegra takes one Redis URL and cannot follow Sentinel; runs are recovered from PostgreSQL if Redis restarts.

Troubleshooting

The deployment is stuck and cpln logs returns nothing

A secret named in the values does not exist. Read status.versions[].message with cpln workload get-deployments RELEASE_NAME-aegra --gvc GVC_NAME -o yaml, create the secret, then run cpln workload force-redeployment RELEASE_NAME-aegra --gvc GVC_NAME.

Aegra restarts a few times on first install

Aegra exits when PostgreSQL or Redis is not up yet and the platform restarts it. It settles once both are ready; no action is needed.

Streams or /runs/wait calls are cut off on the public URL

The public endpoint cuts requests after aegra.requestTimeoutSeconds (default 600, maximum 3600). Raise it for longer calls. Calls from inside the GVC over cpln.local are not subject to it.

A run ends in error with couldn't get a connection after 30.00 sec

The database was unreachable for more than 30 seconds, for example during a PostgreSQL failover. Aegra keeps restarting until the database answers, and the API returns 500 or 503 meanwhile. Submit the run again.

Assistant 'stress_test' not found

Your own image serves only your graphs; the example agents of the default image are not registered. Call your graph by the name listed in aegra.json.

A secret was rotated but Aegra still uses the old value

Rotating a secret does not restart Aegra. Run cpln workload force-redeployment RELEASE_NAME-aegra --gvc GVC_NAME.

The chart refuses to render

The template rejects redis.mode other than dev, extraEnv or agentSecrets.keys names that it sets itself (such as DATABASE_URL, REDIS_URL, RUN_MIGRATIONS_ON_STARTUP, LANGFUSE_* and CPLN_*), duplicate or invalid env names, agentSecrets.keys without agentSecrets.secretName, aegra.replicas above 10, aegra.requestTimeoutSeconds above 3600, and enabling both or neither database. The error names the offending value.

Important Notes

Aegra has no authentication unless your image configures an auth handler in aegra.json. Keep publicAccess off without one: anyone with the URL could run your agents and read every thread.
Langfuse in another GVC: set that Langfuse release’s internalAccess to same-org, or Aegra cannot reach it.
After rotating any secret the release uses, run cpln workload force-redeployment RELEASE_NAME-aegra --gvc GVC_NAME.
Firewall changes (publicAccess, internalAccess) take from 30 seconds to several minutes to take effect.
The first helm upgrade after an install can restart the bundled database and Redis, which briefly interrupts the API.
Use a single-location GVC: the bundled database and Redis run in one location.
Uninstalling deletes the database volume, and with it every thread, run and checkpoint.

External References

Aegra documentation

Concepts, configuration and API

Aegra deployment guide

Deploying Aegra

Aegra authentication

Adding an auth handler

Aegra on GitHub

Source and issues

Agent Chat UI

Browser chat frontend for LangGraph servers

Template Catalog

Templates

Aegra

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Aegra

Agent secrets

Access

Langfuse tracing

Database

Redis

Bring Your Own Agent

Connecting

Chat With an Agent in a Browser

Operations

Backing Up

Scaling and Availability

Troubleshooting

Important Notes

External References

Aegra documentation

Aegra deployment guide

Aegra authentication

Aegra on GitHub

Agent Chat UI

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Aegra

​Agent secrets

​Access

​Langfuse tracing

​Database

​Redis

​Bring Your Own Agent

​Connecting

​Chat With an Agent in a Browser

​Operations

​Backing Up

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Aegra documentation

Aegra deployment guide

Aegra authentication

Aegra on GitHub

Agent Chat UI

Overview

What Gets Created

Prerequisites

Installation

Configuration

Aegra

Agent secrets

Access

Langfuse tracing

Database

Redis

Bring Your Own Agent

Connecting

Chat With an Agent in a Browser

Operations

Backing Up

Scaling and Availability

Troubleshooting

Important Notes

External References