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.
Recommended path
#- Author the schema and generate types. Do this before writing code that reads a new key.
- Load a stage locally and in tests. Keep ordinary tests provider-free.
- Configure providers, CI exports, and immutable snapshots only for trusted deployment workflows. Use
brix env export <stage> --target githubfor later CI steps without AWS, orbrix env upload <stage> --account <id> --region <region>for an AWS runtime snapshot.
Where each command gets its configuration
#brix devresolves thedevelopmentstage, including local overrides, through your providers.brix testandbrix buildload no environment unless you pass--env(tests only; it loads the reservedtest-runstage) or--stage <stage>.test-runholds fake test values and cannot be built, uploaded, or exported, so a deployed stage namedtestis 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 localbrix startof a production build.- Deployed Node and Lambda runtimes read one exact AWS snapshot selected by
SECRETS_ARNandSECRETS_VERSION, once per process. Cloudflare and Fastly use the same snapshot format through worker bindings. - 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: 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.