> [Agent navigation index](/llms.txt)

# Environment and Secrets

Brix uses Varlock for one authored environment schema per application. That schema is the source of truth for validation, generated TypeScript types, secrecy, and what reaches deployment snapshots. Loading is always explicit, so local commands, tests, and deployed runtimes each use a known stage and provider boundary.

This applies to full-stack applications. Managed React applications have no Brix environment integration; they pass public per-mode values through `vite.define`, as described in the [managed React guide](/docs/react-managed.md).

## Recommended path

1. [Author the schema and generate types](/docs/environment-schema.md). Do this before writing code that reads a new key.
1. [Load a stage locally and in tests](/docs/environment-loading.md). Keep ordinary tests provider-free.
1. [Configure providers, CI exports, and immutable snapshots](/docs/environment-secrets.md) only for trusted deployment workflows. Use `brix env export <stage> --target github` for later CI steps without AWS, or `brix env upload <stage> --account <id> --region <region>` for an AWS runtime snapshot.

## Where each command gets its configuration

- `brix dev` resolves the `development` stage, including local overrides, through your providers.
- `brix test` and `brix build` load no environment unless you pass `--env` (tests only; it loads the reserved `test-run` stage) or `--stage <stage>`. `test-run` holds fake test values and cannot be built, uploaded, or exported, so a deployed stage named `test` is unaffected by test runs. Route tests inject fixtures through the test harness instead.
- `brix env run <stage> -- <brix-command>` resolves a stage for one Brix command, such as a script or a local `brix start` of a production build.
- Deployed Node and Lambda runtimes read one exact AWS snapshot selected by `SECRETS_ARN` and `SECRETS_VERSION`, once per process. Cloudflare and Fastly use the same snapshot format through [worker bindings](/docs/deployment-workers.md).
- Later GitHub Actions steps receive only allowlisted values from `brix env export`.

Application code never reads `process.env`. Request handlers read validated values from `c.env`, and scripts call the typed `loadEnv` binding.

Runtime `createEnv` validates the snapshot envelope and key names, then deeply freezes the values; it does not rerun your schema's application rules. Varlock enforces those rules when it loads or uploads values.

For shared-state delivery, use [Terraform-first deployment](/docs/deployment-terraform.md): prepare all
application environments before uploads, persist idempotency tokens and receipts, and bind exact
versions through project-owned Terraform. Upload requires an explicit account and region, and
consent for ambient application overrides; it does not activate code or manage infrastructure state.
