diff --git a/src/pages/docs/self-hosting/configuration/environment.mdx b/src/pages/docs/self-hosting/configuration/environment.mdx
new file mode 100644
index 00000000..c56cc2c4
--- /dev/null
+++ b/src/pages/docs/self-hosting/configuration/environment.mdx
@@ -0,0 +1,130 @@
+---
+title: "Environment variables"
+description: "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 only thing you *must* change before sharing the instance is the `CHANGEME` secrets.
+
+```bash
+cp .env.example .env
+```
+
+<TLDR>
+Doing a local trial? Skip to [Docker Compose](/docs/self-hosting/docker-compose). The defaults work as-is. Come back here when you're ready to set secrets, add LLM provider keys, or turn on email.
+</TLDR>
+
+## Required Secrets
+
+Replace every `CHANGEME` in this group before anyone else can reach the instance. Generate each value 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](/docs/self-hosting/troubleshooting). Set it before your first `docker compose up`.
+</Warning>
+
+## Database Credentials
+
+| Variable | Default | Notes |
+|---|---|---|
+| `PG_USER` | `futureagi` | PostgreSQL username |
+| `PG_PASSWORD` | `CHANGEME` | **Must change** |
+| `PG_DB` | `futureagi` | PostgreSQL database name |
+| `MINIO_ROOT_USER` | `futureagi` | MinIO username |
+| `MINIO_ROOT_PASSWORD` | `CHANGEME` | **Must change** |
+| `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](/docs/self-hosting/requirements#ports-reference), 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](/docs/self-hosting/configuration).
+
+## LLM Gateway
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTCC_INTERNAL_API_KEY` | `CHANGEME` | **Must change.** 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 for the full setup.
+
+## 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 manually from the Django shell after bringing up the stack. 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. Changing them requires a rebuild: `docker compose build frontend`.
+</Warning>
+
+| 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 |
+
+## Dive deeper
+
+<CardGroup cols={2}>
+  <Card title="System Configuration" icon="sliders" href="/docs/self-hosting/configuration">
+    Point the LLM gateway at your providers and set up PeerDB mirrors
+  </Card>
+  <Card title="Production hardening" icon="shield" href="/docs/self-hosting/production">
+    Harden the instance before exposing it to users
+  </Card>
+</CardGroup>