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

# Loading and testing environments

Select environment layers explicitly for local commands, workspace members, scripts, and production-shaped tests.

First complete [the schema and generated type](/docs/environment-schema.md). Then decide whether the
current task is a development server, provider-free unit test, managed E2E server, or script—the
correct command and inclusion of local overrides differ for each.

## Load environments explicitly

```sh
brix dev
brix dev --stage production
brix dev --stage production --no-local
brix dev --no-env
brix test
brix test --env
brix test --stage pre-prod --project node
brix build
brix build --stage production --no-local
brix env run development -- run scripts/seed.ts

```

What each form loads:

- `brix dev` resolves the `development` stage with local overrides; `--stage` selects another stage and `--no-local` drops the local layers. `brix dev --no-env` skips resolution and is meant only for a process that already inherited a resolved environment.
- `brix test` resolves nothing by default. `--env` loads the `test-run` stage; `--stage <stage>` selects another.
- `brix build` resolves nothing by default and has no implicit stage: pass `--stage <stage>` when the build needs configuration. `brix build --env` is rejected so `test-run` values can never reach a deployable build by accident.
- `--no-local` requires `--env` or `--stage` for tests, and `--stage` for builds.
- Managed E2E is different: when no resolved environment was inherited, its server loads the `test-run` stage including `.env.local` and `.env.overrides`. Keep that stage provider-free with fake values if E2E must run offline.

`test-run` is reserved for test values: `brix build --stage test-run`, `brix env run test-run -- build`,
`brix env export test-run`, `brix env upload test-run`, and a `test-run` promotion stage are
rejected. Any other name, including `test`, is an ordinary deployment stage, so a deployed `test`
environment's configuration never reaches `brix test --env` or managed E2E.

Loading order is schema, base, selected stage, local, overrides, then process values. `--no-local`, `brix env export`, and `brix env upload` select only schema, base, and stage. There is no implicit root `.env`, bare `.env`, or `.env.<stage>.local` discovery.

In a workspace, select the owning application on the outer command:

```sh
brix dev#booking
brix env#booking run development -- run scripts/seed.ts
brix env#booking upload production --account 123456789012 --region eu-west-1

```

Each application owns its schema and generated type; there is no sibling or workspace-root fallback.
Unlike local loading, `brix env export` and `brix env upload` reject an ambient process value for an
application key unless you consent to it with repeatable `--allow-override KEY`; internal provider
authentication is allowed. Both also refuse to run inside an injected `brix env run` environment.
For multi-application deployment, prepare all environments before any write with `brix/env/upload`,
not sequential CLI uploads; see [Terraform-first deployment](/docs/deployment-terraform.md).

`brix env run` accepts exactly one stage and a Brix command after `--`. The command cannot be
another `brix env` command or carry a workspace selector; put the selector on `env` instead.
Before Varlock resolves providers, Brix rejects a target that is not a Brix command and reserved
names declared in the schema. Before the injected command runs, it rejects a resolved `STAGE` that is
sensitive or differs from the selected stage, and reserved names from any layer. The same checks
apply to `brix dev`, `brix build --stage`, and `brix test --env`.

Resolving a stage also fails while `SECRETS_ARN` or `SECRETS_VERSION` is set, because `loadEnv()`
would read that deployed AWS snapshot instead of the selected stage. This matters in a GitHub job
after `brix env upload` exports the pair: unset both (or use a separate job) before a later
`brix env run`, `brix dev`, `brix build --stage`, or `brix test --env` step. The managed E2E
server applies the same check before it resolves the `test-run` stage.

The Varlock wrapper forwards `SIGINT` and `SIGTERM` it receives to its child and waits for the child
to exit. Put graceful cleanup in the child application's signal handling rather than assuming
Varlock exits immediately after forwarding a signal.

## Read configuration in a script

Generated applications provide a typed `loadEnv` binding in `src/env.script.ts`. A script imports
that binding, rather than reading process values or importing the inert server declaration:

`scripts/check-catalog.ts`

```ts
import { loadEnv } from "#brix/env/script";

const env = await loadEnv();
const response = await fetch(env.CATALOG_URL, {
  headers: { authorization: `Bearer ${env.CATALOG_TOKEN}` },
});
if (!response.ok) throw new Error(`Catalog check failed (${response.status})`);

```

This example uses the keys from [the schema guide](/docs/environment-schema.md). Run it with explicit
stage selection:

```sh
brix env run development -- run scripts/check-catalog.ts

```

The outer command resolves the selected files and providers; `loadEnv()` reads that resolved
payload and reuses it for later calls in the same process. Plain `brix run scripts/check-catalog.ts`
does not load dotenv files and fails with "No validated environment is available" when neither a
resolved payload nor an exact AWS snapshot is present. This includes steps after `brix env export`:
exported keys are plain process variables, not a resolved payload, so read them from `process.env`
or resolve again with `brix env run`. Scripts in deployment jobs may instead read the exact
`SECRETS_ARN`/`SECRETS_VERSION` pair using their own AWS identity. Never print the returned object
or response bodies that may contain credentials.

## Start a production build locally

`brix start` serves an existing Node build from `dist/app.mjs`. It loads no dotenv files itself:
each request reads configuration from the same sources as `loadEnv()`. To smoke a production build
on your machine, resolve the stage around the command:

```sh
brix build --platform node
brix env run production --no-local -- start

```

`start` reads only `HOST` (default `0.0.0.0`) and `PORT` (default `3000`) from its own process, and
sets `NODE_ENV=production` when unset. A deployed Node process instead receives the exact
`SECRETS_ARN` and `SECRETS_VERSION` pair and an AWS identity that can read that version; see
[secrets and deployment snapshots](/docs/environment-secrets.md). Without either source, requests fail
with a 500 rather than falling back to process values.

## Test safely

Keep unit tests independent of secret providers. Supply environment fixtures through the harness without replacing modules or bypassing production validation:

`src/test/harness.ts`

```ts
import { createTestHarness } from "brix/test";
import { createBrixApp } from "brix/server";
import { brixServer } from "#brix/server";

export const { testApi, testFragment, testPage, testResponse, withOptions } = createTestHarness({
  createApp: () => createBrixApp(brixServer),
  env: {
    STAGE: "test-run",
    PORT: 3000,
    CATALOG_URL: "http://catalog.test",
    CATALOG_TOKEN: "fixture-catalog-token",
  },
});

```

This is the generated `#brix/test` binding with fixture values for the schema guide's keys. Handlers
and loaders consume the fixture through `c.env`, using the same request adapter and snapshot
parser as production. That parser validates the snapshot envelope, JSON values, and permitted key
names; it does not execute the Varlock schema or enforce the generated TypeScript type at runtime.
Keep fixture values consistent with the authored schema. Test schema constraints separately by
loading the `test-run` stage with `brix test --env --project node`. Use sufficiently long fake sensitive
values in `env/.env.test-run`, and never print resolved configuration. See
[server setup](/docs/server.md) and [Contentful](/docs/contentful.md) for safe consumption.

## Custom Lambda initialization

A declared custom Lambda entry uses `defineLambdaHandler({ env, create })` from `brix/lambda`,
with the inert `env` declaration imported from `#brix/env`. It does not use the script-only
`#brix/env/script` loader. Only the declared entry may import the Lambda wrapper; HTTP routes
continue to read `c.env`.

Imports and builds stay provider-free. The first invocation loads the exact
`SECRETS_ARN`/`SECRETS_VERSION` snapshot and calls the factory with resolved configuration.
Concurrent calls share initialization, successful initialization is cached, and initialization
rejection allows a later retry. Both selectors are required: there is no `AWSCURRENT`, ambient
application-value override, or Varlock fallback.

Normal tests inject configuration into the application factory and call its raw event handler.
Wrapper tests and deployed Lambda invocations can exercise the exact snapshot boundary.
Custom-handler `brix dev` is unsupported; use direct tests or an event runner. See
[custom Lambda setup and 2.1/2.2 migration](/docs/deployment-node-aws.md#custom-lambda-handlers).

When local and test loading is predictable, continue to [secrets and deployment snapshots](/docs/environment-secrets.md).
