Configuration

Bootstrap settings live in .env. Models, credentials and integrations are set in the dashboard, and any secrets entered there are stored encrypted in PostgreSQL.

.env

Copy .env.example to .env. Docker Compose reads it, and so does every engine service.

Required

Variable	What it does
DB_PASSWORD	Database password, also used by the postgres container. It goes into DATABASE_URL, so leave out @, /, : and similar characters. openssl rand -hex 16 is safe.
MASTER_ENCRYPTION_KEY	Encrypts the credential registry. Base64, at least 32 characters. Generate it with openssl rand -base64 32 and back it up.
JWT_SECRET	Signs dashboard session tokens. It must be at least 32 bytes and not the placeholder, or the dashboard won’t start. Generate it with openssl rand -hex 32.

Database and bus

Variable	Default	What it does
DB_USER	ae_user	Database user, also used by the postgres container.
DATABASE_URL	built from DB_USER and DB_PASSWORD	PostgreSQL connection URL. Change it only to use an external database.
KAFKA_BROKERS	kafka:9092	Comma-separated Kafka brokers.
QDRANT_URL	http://qdrant:6333	Qdrant REST endpoint.
GITHUB_SERVICE_URL	http://github-service:8085	Internal URL of github-service.

Ports

Variable	Default	Service
DASHBOARD_UI_PORT	32900	Dashboard UI
DASHBOARD_PORT	8080	Dashboard API
WEBHOOK_PORT	8081	Webhook listener (/webhook/github, /webhook/jira)
GATEWAY_PORT	8082	Intake gateway
ONBOARDING_PORT	3321	Onboarding service
PORTAL_PORT	3100	Request portal

Pool sizes and gates

Variable	.env.example value	What it does
RESEARCH_POOL_SIZE	2	Research agent replicas.
IMPL_POOL_SIZE	1	Implementation agent replicas.
QA_POOL_SIZE	1	QA agent replicas.
MAX_RETRY_COUNT	3	Retries before a work item is escalated.
HUMAN_REVIEW_REQUIRED	true	Require human review before pull requests are merged.

Each extra agent replica uses more memory, so raise pool sizes only when Docker has room for them.

Codex re-plan and grounding

All five are read by status-orchestrator. None of them is in .env.example; set one only to change its default.

Variable	Default	What it does
CODEX_REPLAN_DEBOUNCE	10m	Quiet window after the last codex change of a product and branch before in-flight work is re-planned.
CODEX_REPLAN_MAX	2	Automatic re-plans per work item; after that the operator is asked.
CODEX_REPLAN_MIN_TOKENS	a tenth of the item’s budget	Tokens a re-plan needs; with less left, the operator is asked instead.
CODEX_REINDEX_TIMEOUT	2h	How long a Re-index chosen on an empty-codex refusal may stay pending before the item is escalated again.
CODEX_GAP_THRESHOLD	5	Empty codex lookups per run before the evidence is marked ungrounded, which is never released or approved automatically.

Redis (optional)

Variable	Default	What it does
REDIS_URL	empty (off)	Shares the dashboard WebSocket fan-out and the portal and LLM router rate limits between replicas. Leave it empty on a single node. To use the bundled Redis, run docker compose --profile scale up -d redis and set redis://redis:6379/0.

dashboard-backend refuses to start with DASHBOARD_REPLICAS above 1 and no REDIS_URL. If Redis becomes unreachable, rate limits fall back to per-process counting and the dashboard to direct delivery, and both are logged.

Implementation worktrees

Each implementation task runs in its own git worktree under the repository cache, marked by a .ae-worktree.json file. When the implementation agent starts, it reclaims marked worktrees that a crashed process left behind. It never touches directories without a marker.

Variable	Default	What it does
AE_WORKTREE_RECONCILE	on	Reconciliation at startup. off, 0 or false disables it; do that when two agent processes share one host.
AE_WORKTREE_STALE_AFTER	24h	A marker written on another host is left alone until it is older than this. Set it above your longest task.
AE_WORKTREE_RECONCILE_TIMEOUT	5m	Time limit for the startup scan.
AE_REPO_CACHE_ROOT	/repo-cache	Where clones and worktrees live (the compose volume).

The comments in .env.example cover the edge cases, such as replica hostnames after a recreate and worktrees from before an upgrade that have no marker.

Evidence release gate

EVIDENCE_COMPAT_WINDOW (default legacy) decides what five services do with a message that carries no verification evidence: status-orchestrator, implementation-planner, pr-coordinator, review-agent and qa-agent. With legacy, they fall back to the old success flag and count each fallback in ae_evidence_compat_legacy_fallback_total on the service’s /metrics endpoint. With strict, they block those messages, and any other value also counts as strict. All five services read this one variable, so change it for all of them together. .env.example lists what has to be true before you switch to strict.

GitHub webhook secret

The webhook listener reads GITHUB_WEBHOOK_SECRET, even though it is not in .env.example. When it is set, every GitHub webhook delivery must carry a valid HMAC-SHA256 signature made with that secret. When it is empty, signatures go unchecked. If the webhook port can be reached from outside your machine, set it in .env and give GitHub the same secret in the webhook settings.

In the dashboard

Everything else is set in the dashboard’s Admin section. Secrets entered there are encrypted with MASTER_ENCRYPTION_KEY before they are stored.

Page	What you configure
Providers	LLM providers (Ollama, OpenAI, Anthropic, vLLM or a custom OpenAI-compatible endpoint) with their endpoints, API keys and models.
Embeddings	Embedding providers for the vector index.
Agents	Agent definitions: the provider and model each agent uses, and which pipeline steps are on.
Prompts	The prompt templates the agents use.
Credentials	Stored credentials, by scope and category.
Integrations	GitHub accounts (personal access tokens, several per username, each with a label) and Jira (URL, credentials, JQL filter, polling interval, ingest label).
Products	Products, their repositories and onboarding.
Watched Branches	The branches the codex tracks.
System	Pool sizes, escalation, and human review settings.
Auth and Users	Sign-in providers (local accounts, LDAP, SAML) and the users who can sign in.
Config Versions and Rollouts	Snapshots of prompt and model configuration, shadow evaluation, and rollout gates for changes.
Audit	The audit log.

Kubernetes

The repository has a Helm chart under deploy/helm. These docs cover only the Docker Compose deployment.