Configuration

Aegra uses a JSON configuration file (aegra.json) to define graphs, authentication, HTTP settings, the semantic store, and checkpointer settings (thread TTL and the default checkpoint durability).

Config file resolution

Aegra resolves configuration files in this order:

AEGRA_CONFIG environment variable — absolute or relative path
aegra.json in the current working directory
langgraph.json in the current working directory (compatibility fallback)

# Use a custom config file
AEGRA_CONFIG=production.json aegra dev

# Use default aegra.json
aegra dev

Complete example

{
  "dependencies": ["./shared"],
  "graphs": {
    "agent": "./src/react_agent/graph.py:graph",
    "agent_hitl": "./src/react_agent_hitl/graph.py:graph"
  },
  "auth": {
    "path": "./my_auth.py:auth",
    "disable_studio_auth": false
  },
  "http": {
    "app": "./custom_routes.py:app",
    "enable_custom_route_auth": false,
    "cors": {
      "allow_origins": ["https://example.com"],
      "allow_origin_regex": "^https://[a-z0-9-]+\\.example\\.com$",
      "allow_credentials": true
    }
  },
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 5,
      "sweep_limit": 10000
    },
    "durability": "async"
  }
}

`dependencies`

Add shared utility module paths to sys.path before graphs are loaded.

{
  "dependencies": ["./shared", "./libs/common"]
}

Type	Description
`list[str]`	List of directory paths to add to `sys.path`

Relative paths are resolved from the config file’s directory
Paths are added in order (first has highest import priority)
Non-existent paths generate a warning but don’t prevent startup

See dependencies guide for details.

`graphs`

Define your LangGraph agents.

{
  "graphs": {
    "agent": "./src/react_agent/graph.py:graph",
    "custom_agent": "./src/custom/graph.py:my_graph"
  }
}

Field	Type	Description
Key	`string`	Graph ID (used in API calls to identify the graph)
Value	`string`	Import path in format `./path/to/file.py:variable`

The variable can be:

A compiled graph — result of builder.compile() (static, cached once at startup)
A 0-arg callable — called once at startup to produce the graph (e.g., for MCP adapter setup)
A factory function — called per-request with config and/or ServerRuntime to produce a graph customized for the current user or request context

Static graphs

builder = StateGraph(State)
# ... define nodes and edges
graph = builder.compile()  # Export as 'graph'

Factory graphs

Export a callable that accepts config (a RunnableConfig dict), runtime (a ServerRuntime), or both:

from langgraph_sdk.runtime import ServerRuntime

def graph(runtime: ServerRuntime):
    """Per-request factory — called with user context."""
    user = runtime.user
    store = runtime.store
    # Customize graph based on user/context
    builder = StateGraph(State)
    # ...
    return builder.compile()

Supported factory signatures:

def graph() — 0-arg, called once at startup
def graph(config: dict) — receives the RunnableConfig per-request
def graph(runtime: ServerRuntime) — receives runtime with user, store, and access context
def graph(config: dict, runtime: ServerRuntime) — receives both (any parameter order)

Async factories and factories returning async context managers are also supported.

Typed context with `Runtime[T]` (node-level)

When a run is created with a context dict, Aegra passes it to graph.astream(context=...). LangGraph core coerces it to a typed object and injects it into nodes via Runtime[T]. This works for both static and factory graphs:

from dataclasses import dataclass
from langgraph.graph import StateGraph
from langgraph.runtime import Runtime

@dataclass
class MyContext:
    model_name: str = "openai/gpt-4o-mini"
    temperature: float = 0.7

class State(TypedDict):
    messages: list

async def call_model(state: State, runtime: Runtime[MyContext]):
    """Node receives typed context via Runtime injection."""
    model = runtime.context.model_name      # str, typed
    temp = runtime.context.temperature      # float, typed
    ...

builder = StateGraph(State, context_schema=MyContext)
builder.add_node("call_model", call_model)
...
graph = builder.compile()

Pydantic BaseModel and dataclass types are both supported. Declare context_schema= on StateGraph and add a runtime: Runtime[T] parameter to any node that needs it.

Factory-level context with `ServerRuntime[T]`

For factory graphs, ServerRuntime[T] provides typed context at graph-build time — before execution starts. Use this for structural decisions that change the graph topology (adding/removing nodes, selecting tools, managing resource lifecycle):

from langgraph_sdk.runtime import ServerRuntime

@asynccontextmanager
async def graph(runtime: ServerRuntime[MyContext]):
    ert = runtime.execution_runtime
    ctx = ert.context if ert else MyContext()

    # Structural decision — changes graph topology
    tools = [search_tool] if ctx.enable_search else []
    compiled = build_graph(tools)
    yield compiled

Use runtime.execution_runtime to check whether the factory is being called for actual execution (returns the execution runtime with .context) or for introspection like schema extraction (returns None). When to use which:

Need	Use	Works with
Read context in node functions	`Runtime[T]` on node parameter	Static + factory graphs
Change graph structure per request	`ServerRuntime[T]` in factory	Factory graphs only
Manage resource lifecycle (MCP, DB)	`ServerRuntime[T]` + async context manager	Factory graphs only
Filter tools by user permissions	`ServerRuntime` (`.user`) in factory	Factory graphs only

For a complete example combining both layers, see examples/factory/.

`auth`

Configure authentication and authorization.

{
  "auth": {
    "path": "./my_auth.py:auth",
    "disable_studio_auth": false
  }
}

Field	Type	Default	Description
`path`	`string`	—	Import path to your auth handler (`./file.py:variable`)
`disable_studio_auth`	`bool`	`false`	Disable auth for LangGraph Studio connections

The path supports multiple formats:

./auth.py:auth — Load from a file relative to the config
./src/auth/jwt.py:auth — Nested path
mypackage.auth:auth — Load from an installed package

If auth is not configured, Aegra runs in no-auth mode where all requests are allowed. See authentication guide for details.

`http`

Configure custom routes and CORS.

{
  "http": {
    "app": "./custom_routes.py:app",
    "enable_custom_route_auth": false,
    "cors": {
      "allow_origin_regex": "^https://[a-z0-9-]+\\.example\\.com$"
    }
  }
}

Field	Type	Default	Description
`app`	`string`	`None`	Import path to custom FastAPI app
`enable_custom_route_auth`	`bool`	`false`	Require Aegra auth on every FastAPI route in the custom app. See custom routes for what it covers
`cors.allow_origins`	`list[str]`	`["*"]` (`[]` if `allow_origin_regex` is set)	Allowed CORS origins
`cors.allow_origin_regex`	`string`	`None`	Regular expression for additional allowed origins; when present without `allow_origins`, the origin-list default is `[]`
`cors.allow_credentials`	`bool`	`false` with a regex or wildcard origins, `true` with concrete origins and no regex	Allow credentials in CORS requests

When allow_origin_regex is non-null, it is passed to Starlette’s CORSMiddleware and matched against the complete origin. If allow_origins is also provided, either the list or regex can authorize an origin. An explicit allow_origins: ["*"] remains a wildcard. An empty string still counts as configured; it does not match normal non-empty origins. Note: the allow_credentials default only recognizes an exact ["*"] or "*". A wildcard mixed with other concrete origins (e.g. ["*", "https://example.com"]) currently still defaults allow_credentials to true, even though Starlette treats that list as allow-all — tracked in #633. Set allow_credentials explicitly if you use a mixed list. See custom routes guide for details.

`store`

Configure semantic store with vector embeddings.

{
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  }
}

Field	Type	Required	Description
`index.dims`	`integer`	Yes	Embedding vector dimensions (must match your model)
`index.embed`	`string`	Yes	Embedding model in format `provider:model-id`
`index.fields`	`list[str]`	No	JSON fields to embed (default: `["$"]` for entire document)

If store is not configured, Aegra operates in basic key-value mode. See semantic store guide for details.

`checkpointer`

Configure thread retention (TTL) and the default checkpoint durability.

`ttl`

When a ttl block is present, every newly created thread gets an expiry, and a background sweep deletes or compacts expired threads.

{
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 5,
      "sweep_limit": 10000
    }
  }
}

Field	Type	Default	Description
`ttl.strategy`	`string`	`delete`	`delete` removes the thread, its runs/crons, and all checkpoint data. `keep_latest` prunes checkpoint history but keeps the thread and its latest state, then re-arms the TTL (periodic compaction).
`ttl.default_ttl`	`number`	`43200`	Default thread TTL in minutes (43200 = 30 days), applied to threads created after TTL is enabled.
`ttl.sweep_interval_minutes`	`number`	`5`	How often the background sweep runs.
`ttl.sweep_limit`	`integer`	`10000`	Max threads processed per sweep iteration.

Notes:

Threads with pending or running runs are skipped and swept once their runs settle.
Deleting an expired thread cascades to its runs and thread-bound crons.
Individual threads can override the default via the ttl field on POST /threads; expired threads can be cleaned immediately with POST /threads/prune. See the threads guide.
The AEGRA_THREAD_TTL environment variable replaces this block entirely when set — see environment variables.

If neither checkpointer.ttl nor AEGRA_THREAD_TTL is configured, threads never expire.

`durability`

Sets when checkpoints are written for runs that do not choose a mode themselves.

{
  "checkpointer": {
    "durability": "exit"
  }
}

Field	Type	Default	Description
`durability`	`string`	unset	`sync`, `async`, or `exit`. `AEGRA_CHECKPOINT_DURABILITY` overrides it. With neither set, runs keep LangGraph’s default, `async`.

Resolution order for each run:

The run’s durability field (or the deprecated checkpoint_during).
The AEGRA_CHECKPOINT_DURABILITY environment variable.
checkpointer.durability in aegra.json.
LangGraph’s default.

An invalid value stops the server at startup. LangGraph Platform has no server-wide durability setting, so this key is specific to Aegra. See checkpoint durability for what each mode trades off.

Common configurations

Minimal

{
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  }
}

With authentication

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

With custom routes

{
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "http": {
    "app": "./custom_routes.py:app"
  }
}

Production

{
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "auth": {
    "path": "./auth/production_auth.py:auth"
  },
  "http": {
    "app": "./custom_routes.py:app",
    "enable_custom_route_auth": true,
    "cors": {
      "allow_origins": ["https://myapp.com"],
      "allow_credentials": true
    }
  }
}

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

Configuration

Config file resolution

Complete example

`dependencies`

`graphs`

Static graphs

Factory graphs

Typed context with `Runtime[T]` (node-level)

Factory-level context with `ServerRuntime[T]`

`auth`

`http`

`store`

`checkpointer`

`ttl`

`durability`

Common configurations

Minimal

With authentication

With custom routes

Production

​Config file resolution

​Complete example

​dependencies

​graphs

​Static graphs

​Factory graphs

​Typed context with Runtime[T] (node-level)

​Factory-level context with ServerRuntime[T]

​auth

​http

​store

​checkpointer

​ttl

​durability

​Common configurations

​Minimal

​With authentication

​With custom routes

​Production

Config file resolution

Complete example

`dependencies`

`graphs`

Static graphs

Factory graphs

Typed context with `Runtime[T]` (node-level)

Factory-level context with `ServerRuntime[T]`

`auth`

`http`

`store`

`checkpointer`

`ttl`

`durability`

Common configurations

Minimal

With authentication

With custom routes

Production