Environment Variables

AEGIS uses a single .env file at the repository root. All services load it at startup using python-dotenv. Copy .env.example to get started:


cp .env.example .env

Complete Variable Reference

Database

Variable	Required	Default	Description
`DATABASE_URL`	Yes	`postgresql://aegis:aegis_local@localhost:5432/aegis`	PostgreSQL connection string. Used by all Python services that need database access (orchestration engine, memory service, knowledge graph service, approval service, compliance monitor, flaring monitor).

Redis

Variable	Required	Default	Description
`REDIS_URL`	Yes	`redis://localhost:6379`	Redis connection URL. Used by the memory service for working memory (Redis Hash) and the injection ledger (Redis Hash at `skill:ledger:{conversation_id}`).

Kafka

Variable	Required	Default	Description
`KAFKA_BOOTSTRAP_SERVERS`	Yes	`localhost:9092`	Kafka broker address. Used by the ingestion service for publishing entity extraction events.

LLM Providers

Variable	Required	Default	Description
`OPENAI_API_KEY`	Yes	None	OpenAI API key for LLM calls (gpt-4o, gpt-4o-mini) and embeddings (text-embedding-3-small). Required for agent execution and episodic memory.
`ANTHROPIC_API_KEY`	No	None	Anthropic API key. Optional — only needed if routing LLM calls to Claude models via LiteLLM.
`LITELLM_LOG_LEVEL`	No	`DEBUG`	Log verbosity for the LiteLLM library. Set to `INFO` or `WARNING` to reduce noise.

OPENAI_API_KEY is the only variable you must set manually. Without it, agent execution and episodic memory storage will fail. All other variables have working defaults for local development.

Service Ports

These variables configure which port each service listens on. The defaults match the standard AEGIS port assignments.

Variable	Required	Default	Description
`API_GATEWAY_PORT`	No	`8000`	Go API gateway listen port
`ORCHESTRATION_PORT`	No	`8001`	Orchestration engine listen port
`MEMORY_PORT`	No	`8002`	Memory service listen port
`KNOWLEDGE_GRAPH_PORT`	No	`8003`	Knowledge graph service listen port
`APPROVAL_PORT`	No	`8004`	Approval service listen port
`INGESTION_PORT`	No	`8005`	Ingestion service listen port
`COMPLIANCE_PORT`	No	`8006`	Compliance monitor listen port
`FLARING_PORT`	No	`8007`	Flaring monitor listen port

The auth service always runs on port 8009. Its port is not configurable via environment variable in the current implementation.

Authentication

Variable	Required	Default	Description
`JWT_SECRET`	Yes	`aegis-local-dev-secret-change-in-production`	Secret key for signing and verifying JWT tokens (HS256 algorithm). The auth service uses this to generate tokens, and the gateway uses it to validate them. Must be changed for production.
`BOOTSTRAP_ADMIN_EMAIL`	Yes	`admin@aegis.local`	Email of the initial admin user seeded by the auth service on startup (if no user with that email exists).
`BOOTSTRAP_ADMIN_PASSWORD`	Yes	`aegis-dev-admin`	Password for the seeded bootstrap admin. Must be changed for production.
`HMAC_SIGNING_KEY`	Yes	`aegis-local-hmac-key-change-in-production`	HMAC key used to sign entries in the append-only audit trail. Each audit log row includes an HMAC signature for tamper detection. Must be changed for production. In production, this is managed by HashiCorp Vault.

Observability

Variable	Required	Default	Description
`LANGFUSE_PUBLIC_KEY`	No	None	Langfuse public key for LLM observability tracing.
`LANGFUSE_SECRET_KEY`	No	None	Langfuse secret key.
`LANGFUSE_HOST`	No	`https://cloud.langfuse.com`	Langfuse server URL.

Internal Service URLs

These are used by the orchestration engine to call other services. You typically do not need to change these unless running services on non-default ports.

Variable	Default	Used By
`MEMORY_SERVICE_URL`	`http://localhost:8002`	Orchestration engine
`KNOWLEDGE_GRAPH_SERVICE_URL`	`http://localhost:8003`	Orchestration engine, ingestion service
`APPROVAL_SERVICE_URL`	`http://localhost:8004`	Orchestration engine

Orchestration Engine Tuning

Variable	Default	Description
`DEFAULT_LLM_MODEL`	`gpt-4o`	Default model for LLM calls when not specified in the request
`DEFAULT_MAX_TOKENS_PER_EXECUTION`	`100000`	Token budget per agent execution
`DEFAULT_MAX_COST_PER_EXECUTION`	`5.0`	Dollar cost budget per agent execution
`MAX_GRAPH_ITERATIONS`	`20`	Maximum number of tool-call loop iterations before forcing output
`EPISODIC_TOP_K`	`3`	Number of episodic memories to retrieve per query
`R35_INTEGRITY_FAIL_LOUD`	`true`	R35 startup integrity check mode. When `true` (default since R35 P2), an unresolved `agent_definitions.root_skill_key` / `persona_key` fails loudly at deploy rather than at a tester’s first message. The default was `false` in R35 P1 (warn-not-fail) while the `rrc_rule37` / `rrc_rule32` skills did not yet exist; R35 P2 seeds those skills and flips the default to `true`. Override to `false` only for an environment that has not yet run the P2 seeders.

Example .env File


# Database
DATABASE_URL=postgresql://aegis:aegis_local@localhost:5432/aegis
 
# Redis
REDIS_URL=redis://localhost:6379
 
# Kafka
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
 
# LLM Providers (add your keys)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LITELLM_LOG_LEVEL=DEBUG
 
# Service Ports
API_GATEWAY_PORT=8000
ORCHESTRATION_PORT=8001
MEMORY_PORT=8002
KNOWLEDGE_GRAPH_PORT=8003
APPROVAL_PORT=8004
INGESTION_PORT=8005
COMPLIANCE_PORT=8006
FLARING_PORT=8007
 
# Auth (local dev)
JWT_SECRET=aegis-local-dev-secret-change-in-production
BOOTSTRAP_ADMIN_EMAIL=admin@aegis.local
BOOTSTRAP_ADMIN_PASSWORD=aegis-dev-admin
HMAC_SIGNING_KEY=aegis-local-hmac-key-change-in-production
 
# Observability
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_HOST=https://cloud.langfuse.com

Security Notes

Never commit your .env file. The repository .gitignore excludes it. For production deployments, secrets are managed by HashiCorp Vault — never store production keys in environment files.

The following variables contain sensitive values that must be rotated for production:

JWT_SECRET — compromised value allows forging authentication tokens
BOOTSTRAP_ADMIN_PASSWORD — the default seeds an admin account; set a strong value before deploying
HMAC_SIGNING_KEY — compromised value allows forging audit trail signatures
OPENAI_API_KEY — compromised value allows unauthorized LLM usage at your cost