Skip to main content
Aegra uses a JSON configuration file (aegra.json) to define graphs, authentication, HTTP settings, and the semantic store.

​
Config file resolution

Aegra resolves configuration files in this order:
  1. AEGRA_CONFIG environment variable — absolute or relative path
  2. aegra.json in the current working directory
  3. 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": "./graphs/react_agent/graph.py:graph",
    "agent_hitl": "./graphs/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_credentials": true
    }
  },
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  }
}

​
dependencies

Add shared utility module paths to sys.path before graphs are loaded. 
{
  "dependencies": ["./shared", "./libs/common"]
}
TypeDescription
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": "./graphs/react_agent/graph.py:graph",
    "custom_agent": "./my_graphs/custom.py:my_graph"
  }
}
FieldTypeDescription
KeystringGraph ID (used in API calls to identify the graph)
ValuestringImport path in format ./path/to/file.py:variable
The variable must be a compiled LangGraph graph (result of builder.compile()).

​
auth

Configure authentication and authorization. 
{
  "auth": {
    "path": "./my_auth.py:auth",
    "disable_studio_auth": false
  }
}
FieldTypeDefaultDescription
pathstring—Import path to your auth handler (./file.py:variable)
disable_studio_authboolfalseDisable 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_origins": ["https://example.com"],
      "allow_credentials": true
    }
  }
}
FieldTypeDefaultDescription
appstringNoneImport path to custom FastAPI app
enable_custom_route_authboolfalseApply Aegra auth to all custom routes
cors.allow_originslist[str]["*"]Allowed CORS origins
cors.allow_credentialsboolfalse when origins is ["*"], true otherwiseAllow credentials in CORS requests
See custom routes guide for details.

​
store

Configure semantic store with vector embeddings. 
{
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  }
}
FieldTypeRequiredDescription
index.dimsintegerYesEmbedding vector dimensions (must match your model)
index.embedstringYesEmbedding model in format provider:model-id
index.fieldslist[str]NoJSON 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.

​
Common configurations

​
Minimal

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

​
With authentication

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

​
With custom routes

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

​
Production

{
  "graphs": {
    "agent": "./graphs/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
    }
  }
}