Environment variables

Complete .env reference for a self-hosted Future AGI instance

In this page

Every setting the stack reads at boot comes from a single .env file in the repo root. This page is the complete reference, grouped by what each variable does. The stack boots fine with the shipped defaults. The one thing you must change before sharing the instance is the secrets, which ship with working development values rather than blanks.

cp .env.example .env

Changes apply on the next docker compose up -d, which recreates the containers whose environment changed. Two exceptions are called out below: PG_PASSWORD only takes on Postgres’s very first boot, and the VITE_* variables other than VITE_HOST_API are baked in at image build time.

📝

TL;DR

Doing a local trial? Skip to Installation. The defaults work as-is. Come back here when you’re ready to set secrets, add LLM provider keys, or turn on email.

Required Secrets

Every value in this group has a development default that works out of the box, so nothing warns you when you leave it in place. Replace all four before anyone else can reach the instance, generating each with the command shown.

Variable	Generate with	Used by
`SECRET_KEY`	`openssl rand -hex 32`	Django sessions, CSRF, password reset
`PG_PASSWORD`	`openssl rand -base64 24`	PostgreSQL auth
`MINIO_ROOT_PASSWORD`	`openssl rand -base64 24`	MinIO object storage auth
`AGENTCC_INTERNAL_API_KEY`	`openssl rand -hex 32`	Backend and gateway shared secret

Warning

PG_PASSWORD is written to the Postgres volume on first boot only. If you change it after the volume exists, authentication fails. See the fix in Troubleshooting. Set it before your first docker compose up.

Database Credentials

Variable	Default	Notes
`PG_USER`	`futureagi`	PostgreSQL username
`PG_PASSWORD`	`futureagi`	Must change, set it in Required Secrets above
`PG_DB`	`futureagi`	PostgreSQL database name
`MINIO_ROOT_USER`	`futureagi`	MinIO username
`MINIO_ROOT_PASSWORD`	`futureagi`	Must change, set it in Required Secrets above
`CH_USE_REPLICATED_ENGINES`	`false`	`true` only for multi-node ClickHouse

Ports

Every service port is configurable. The full table (defaults, what each binds to, and exposure scope) lives in Requirements, so you can plan firewall rules in one place.

Backend Runtime

Variable	Default	Description
`ENV_TYPE`	`development`	One of `development`, `staging`, or `prod`. Prod mode disables debug output and enables `check --deploy`
`FAST_STARTUP`	`false`	Skip migrations on restart (dev only). Always `false` in production
`GRANIAN_WORKERS`	`1`	ASGI worker processes. Set to your CPU count in production
`GRANIAN_THREADS`	`2`	Threads per worker
`ENABLE_GRPC`	`true`	Enable the gRPC endpoint
`ENABLE_HTTP`	`true`	Enable the HTTP/REST endpoint

Temporal Worker

Variable	Default	Description
`TEMPORAL_NAMESPACE`	`default`	Temporal namespace
`TEMPORAL_ALL_QUEUES`	`true`	Single worker polls all queues. Set `false` and use the dev overlay for per-queue workers
`TEMPORAL_MAX_CONCURRENT_ACTIVITIES`	`50`	Max concurrent activity tasks
`TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS`	`50`	Max concurrent workflow tasks

Tuning guidance lives in System configuration.

LLM Gateway

Variable	Default	Description
`AGENTCC_INTERNAL_API_KEY`	`local-dev-only-shared-secret-replace-me`	Must change, set it in Required Secrets above. The backend authenticates gateway calls with this shared secret

Setting a key here is only half the job. The gateway also needs a config.yaml listing the providers it may route to. See System configuration.

LLM Provider Keys

Set a key for each provider you’ll use and leave the rest blank. These are read by the gateway via ${VAR} interpolation in config.yaml.

Variable	Provider
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`GOOGLE_API_KEY`	Google Gemini
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION`	AWS Bedrock + S3

Email (Mailgun)

Email delivery powers self-service sign-up and password reset. Without it, you create users from the Django shell during Installation. Set these to turn on the email flow:

Variable	Description
`MAILGUN_API_KEY`	Mailgun private API key
`MAILGUN_SENDER_DOMAIN`	Verified Mailgun sending domain
`DEFAULT_FROM_EMAIL`	`From:` address for outbound email
`SERVER_EMAIL`	`From:` address for Django admin error email

Frontend Build-Time

Warning

These are baked into the JavaScript bundle at Vite build time, and the published images are prebuilt, so changing one means building your own frontend image. VITE_HOST_API is the exception: the frontend container writes it into config.js on start, so changing that one needs only a restart (docker compose up -d frontend).

Variable	Default	Description
`VITE_HOST_API`	`http://localhost:8000`	Backend URL as seen by the browser. In production, use your public backend URL
`VITE_ENVIRONMENT`	`development`	Frontend analytics and feature flags

Optional

Variable	Default	Description
`RECAPTCHA_ENABLED`	`false`	Enable reCAPTCHA on registration
`RECAPTCHA_SECRET_KEY`	`(none)`	reCAPTCHA v2/v3 server-side key
`VITE_GOOGLE_SITE_KEY`	`(none)`	reCAPTCHA client-side key (requires a frontend rebuild)
`FUTURE_AGI_CLOUD_API_KEY`	`(none)`	Enterprise-tier Cloud features only. Leave blank for the open-source build
`FUTURE_AGI_CLOUD_API_URL`	`https://api.futureagi.com`	Do not change

Questions & Discussion