How to: .env Setup & Security
Before running the orchestrator, copy `alpha_factory_v1/.env.sample` to `.env` and
replace all placeholder values with strong secrets. The sample sets
`NEO4J_PASSWORD=REPLACE_ME` as a placeholder—generate a random password for
services like Neo4j and Postgres using `openssl rand -base64 18` or a similar
tool and **never deploy with the defaults**. The orchestrator will refuse to
start if `NEO4J_PASSWORD` remains `REPLACE_ME` or is missing.
Set `API_TOKEN` to a strong secret so that the REST API can authenticate
incoming requests. Clients must send `Authorization: Bearer
`.
The server aborts if `API_TOKEN` equals `REPLACE_ME_TOKEN`.

#### API Token Requirement

Before starting the API server or running the test suite, ensure `API_TOKEN`
is set to a non-default value. The examples in `tests/test_api_status.py` use
`test-token` as a reference token for local runs.
Use `API_RATE_LIMIT` to limit requests per minute per IP (default `60`).
If more than 5% of requests return HTTP `429` within a minute, the server calls
`utils.alerts.send_alert` to report excessive throttling.
Avoid storing private keys directly in `.env`. Instead set
`AGI_INSIGHT_SOLANA_WALLET_FILE` to a file containing your hex-encoded wallet
key and keep that file readable only by the orchestrator.
To enable secure gRPC transport set `AGI_INSIGHT_BUS_CERT`,
`AGI_INSIGHT_BUS_KEY` and `AGI_INSIGHT_BUS_TOKEN`. If these values are
omitted and `AGI_INSIGHT_ALLOW_INSECURE=1`, the bus starts without TLS.
See the [documentation](https://montrealai.github.io/AGI-Alpha-Agent-v0/)
for instructions and example volume mounts.

`.env.sample` notes that paths on Windows may require quotes (e.g., `C:\\path\\to\\file`).

#### Supported Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `OPENAI_API_KEY` | _(empty)_ | API key for hosted models. Offline mode is used when empty. |
| `OPENAI_TIMEOUT_SEC` | `30` | Timeout for OpenAI API requests in seconds. |
| `NO_LLM` | `0` | Set to `1` to skip the LLM planner even when `OPENAI_API_KEY` is provided. |
| `ALPHA_ASI_LLM_MODEL` | `gpt-4o-mini` | Planner model name used by the world model demo. |
| `ALPHA_ASI_SEED` | `42` | Deterministic RNG seed for the demo (can also be set via `general.seed` in `config.yaml`). |
| `ALPHA_ASI_MAX_STEPS` | `100000` | Learner steps before auto-stop. |
| `ALPHA_ASI_BUFFER_LIMIT` | `50000` | Replay-buffer length. |
| `ALPHA_ASI_TRAIN_BATCH` | `128` | SGD mini-batch size. |
| `ALPHA_ASI_MAX_GRID` | `64` | Safety clamp on generated mazes. |
| `ALPHA_ASI_HOST` | `0.0.0.0` | FastAPI bind address for the demo. |
| `ALPHA_ASI_PORT` | `7860` | FastAPI port for the demo. |
| `NEO4J_PASSWORD` | `REPLACE_ME` | Database password required by the orchestrator. |
| `RUN_MODE` | `api` | Launch mode for Compose or Helm (`api`, `cli`, `web`). |
| `PORT` | `8000` | REST API port. |
| `AGI_INSIGHT_OFFLINE` | `0` | Set to `1` to force local inference models. |
| `AGI_INSIGHT_BUS_PORT` | `6006` | gRPC bus port used by the demo. |
| `AGI_INSIGHT_LEDGER_PATH` | `./ledger/audit.db` | Path to the local audit ledger. |
| `AGI_INSIGHT_SECRET_BACKEND` | _(empty)_ | Set to `vault`, `aws` or `gcp` to load secrets from an external manager. |
| `VAULT_ADDR`/`VAULT_TOKEN` | _(empty)_ | Connection details for HashiCorp Vault when using the `vault` backend. |
| `AWS_REGION`/`OPENAI_API_KEY_SECRET_ID` | _(empty)_ | AWS Secrets Manager region and secret ID when using the `aws` backend. |
| `GCP_PROJECT_ID`/`OPENAI_API_KEY_SECRET_ID` | _(empty)_ | GCP project and secret name when using the `gcp` backend. |
| `AGI_INSIGHT_BUS_CERT` | _(empty)_ | Path to the gRPC bus certificate. |
| `AGI_INSIGHT_BUS_KEY` | _(empty)_ | Private key matching `AGI_INSIGHT_BUS_CERT`. |
| `AGI_INSIGHT_BUS_TOKEN` | _(empty)_ | Shared secret for bus authentication. |
| `AGI_INSIGHT_ALLOW_INSECURE` | `0` | Set to `1` to run the bus without TLS when no certificate is provided. |
| `API_TOKEN` | `REPLACE_ME_TOKEN` | Bearer token required by the REST API. Startup fails if unchanged. |
| `API_CORS_ORIGINS` | `*` | Comma-separated list of allowed CORS origins. |
| `SANDBOX_CPU_SEC` | `2` | CPU time limit for sandboxed code. |
| `SANDBOX_MEM_MB` | `256` | Memory cap for sandboxed code in MB. |
| `MAX_RESULTS` | `100` | Maximum stored simulation results. |
| `MAX_SIM_TASKS` | `4` | Maximum concurrent simulation tasks. |
| `IPFS_GATEWAY` | `https://ipfs.io/ipfs` | Base URL for fetching pinned Insight demo runs. Not used for asset downloads. |
| `HF_GPT2_BASE_URL` | `https://huggingface.co/openai-community/gpt2/resolve/main` | Base URL for the GPT‑2 checkpoints. |
| `PYODIDE_BASE_URL` | `https://cdn.jsdelivr.net/pyodide/v0.28.0/full` | Base URL for the Pyodide runtime files. |
| `FETCH_ASSETS_ATTEMPTS` | `3` | Download retry count for `fetch_assets.py`. |
| `FETCH_ASSETS_BACKOFF` | `1` | Base delay between retries in seconds. |
| `OTEL_ENDPOINT` | _(empty)_ | OTLP endpoint for anonymous telemetry. |
| `SKIP_WEBKIT_T