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

# Environment schemas and types

Author the canonical Varlock schema, generate TypeScript declarations, and consume validated request configuration through Brix.

Start in a full-stack application with an `env/` directory. This task is complete when
`brix env types` updates the committed declaration and `brix check` accepts both files; provider
credentials are not needed for type generation.

## Create the schema

Keep `.env.schema`, optional `.env.base`, safe `.env.<stage>` files, and shared `.env.local` under `env/`. Ignore only `env/.env.overrides` for personal overrides. Never commit resolved secrets.

`env/.env.schema`

```dotenv
# @currentEnv=$VARLOCK_ENV
# @generateTsTypes(path=../src/env.generated.d.ts, auto=false, exposeEnv=none, processEnv=none, importMetaEnv=none)
# ---

# @internal @sensitive=false
VARLOCK_ENV=development

# @type=string @required @sensitive=false
STAGE=$VARLOCK_ENV

# @type=number @required @sensitive=false
PORT=3000

# @type=url @required @sensitive=false
CATALOG_URL=https://catalog.example.com

# @type=string @required @sensitive
CATALOG_TOKEN=

```

The required token intentionally has no default. Before running `brix dev`, provide a valid provider
reference or a safe local fixture in the appropriate value file. For the offline `test-run` stage that `brix test --env` and managed E2E load:

`env/.env.test-run`

```dotenv
CATALOG_URL=http://catalog.test
CATALOG_TOKEN=fixture-catalog-token

```

These values are only configuration fixtures; they do not start a catalog service. Route tests inject
fixtures directly, while HTTP-consuming tests still need an MSW handler or a disposable real service.

Declare every application key and type in the schema. Stage and local files supply values, not validation. Mark selection and provider inputs `@internal` so they stay out of application types and deployment snapshots.

## Follow naming rules

`STAGE` must be non-sensitive and equal the selected stage; loading and upload fail otherwise. Stage
names are lowercase identifiers that start with a letter and may contain digits and hyphens;
`schema`, `base`, `local`, and `overrides` are reserved file roles, not stages.

Application keys must match `[A-Za-z_][A-Za-z0-9_]*`. Brix reserves names that shells, Git, SSH,
Terraform, language runtimes, and CI read as executable hooks, trust roots, search paths, or
credentials, because validated values can reach child processes and later CI steps. Reserved names
are compared case-insensitively and fail loading, upload, export, and runtime parsing with an error
that names the key.

- Reserved prefixes: `ACTIONS_`, `AWS_`, `BASH_`, `BRIX_`, `COREPACK_`, `CURL_`, `DOCKER_`, `DYLD_`, `GH_`, `GITHUB_`, `GIT_`, `INPUT_`, `LD_`, `NPM_`, `NUB_`, `OP_`, `PERL`, `PNPM_`, `PYTHON`, `RUNNER_`, `SSH_`, `STATE_`, `STORYBOOK_`, `TF_`, `VARLOCK_`, `VITE_`, `XDG_`, `YARN_`, `__NUB_`, `__VARLOCK_`.
- `BRIX_SERVICE_SIGNING_KEYS` and `BRIX_SERVICE_VERIFY_KEYS` are the only `BRIX_` names an application may declare, in exactly that case. They are the standard names for [service signature](/docs/service-signatures.md) keys, which Brix reads from application configuration; every other `BRIX_` name stays reserved. They must be declared `@sensitive`: Brix refuses them as non-sensitive items, deployment bindings, or CI literal exports.
- Reserved exact names: `ALL_PROXY`, `BROWSER`, `CDPATH`, `CI`, `CLASSPATH`, `EDITOR`, `ENV`, `FTP_PROXY`, `GCONV_PATH`, `GLOBIGNORE`, `GNUPGHOME`, `HISTFILE`, `HOME`, `HOSTALIASES`, `HTTP_PROXY`, `HTTPS_PROXY`, `IFS`, `INPUTRC`, `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, `_JAVA_OPTIONS`, `KUBECONFIG`, `LESSCLOSE`, `LESSOPEN`, `LOCALDOMAIN`, `MANPAGER`, `NETRC`, `NO_PROXY`, `NODE_AUTH_TOKEN`, `NODE_EXTRA_CA_CERTS`, `NODE_OPTIONS`, `NODE_PATH`, `NODE_REPL_EXTERNAL_MODULE`, `NODE_TLS_REJECT_UNAUTHORIZED`, `OPENSSL_CONF`, `PAGER`, `PATH`, `PROMPT_COMMAND`, `PS1`, `PS4`, `REQUESTS_CA_BUNDLE`, `RES_OPTIONS`, `RUBYLIB`, `RUBYOPT`, `SECRETS_ARN`, `SECRETS_VERSION`, `SHELL`, `SHELLOPTS`, `SSL_CERT_DIR`, `SSL_CERT_FILE`, `SUDO_ASKPASS`, `TEMP`, `TMP`, `TMPDIR`, `VISUAL`, `WGETRC`, `ZDOTDIR`.

`VITE_` is reserved because Vite inlines prefixed process variables into browser
`import.meta.env`. Brix additionally sets Vite's `envPrefix` to a reserved `BRIX_` sentinel, so
ambient `VITE_*` variables from a shell or CI step never reach browser bundles; pass browser
constants through `vite.define` instead. `STORYBOOK_` is reserved for the same reason: Storybook
appends it to `envPrefix`, so a schema value exported to a later CI step would otherwise be inlined
into the Storybook bundle.

A non-internal schema key with a reserved name fails before Varlock starts any child process, and
`brix doctor` reports it against `env/.env.schema`.

Rename a colliding application value, for example `GIT_SHA` to `COMMIT_SHA`. `NODE_ENV` and other
unlisted `NODE_` names remain available. Provider credentials such as `OP_SERVICE_ACCOUNT_TOKEN`
belong in `@internal` inputs, which never enter a snapshot.

Useful decorators include `@type=string`, `number`, `boolean`, `url`, or `enum(...)`; `@required` and `@optional`; `@sensitive` and `@sensitive=false`; `@internal`; `@example`; and `@docs(...)`. Varlock defaults sensitivity to true, so classify values explicitly. `@public` means non-sensitive metadata—it does not expose a value to browser code.

Sensitive values must be safe to redact. An explicitly sensitive value shorter than 12 characters
warns; one shorter than 3 characters errors, as do unsuitable values such as booleans, numbers, and
non-string composite elements. Keep numeric-looking secrets as strings. If a real secret is 3–11
characters, acknowledge it with `@sensitive={allowShortValue=true}`; that option cannot allow fewer
than 3 characters. Values swept in by `@defaultSensitive` warn instead of failing, but explicit
classification remains the supported application pattern.

URL domain allowlists match the entire host. Entries contain a hostname and optional port, without a
scheme, credentials, or path. Omitting the port permits any port; including it pins that port. Use an
array for multiple hosts:

```dotenv
# @type=url(allowedDomains=[localhost, api.example.com:8443]) @required @sensitive=false
SERVICE_URL=http://localhost:3000

```

Varlock warns on malformed URLs, whitespace or control characters, missing hosts, and non-HTTP(S)
protocols without explicit `allowedProtocols`; its next major turns these warnings into errors, so
fix them now. Domain allowlists already reject ambiguous host spellings: use `scheme://host`,
canonical IPv4, and punycode for internationalized hosts. Do not weaken an allowlist to silence
validation. Declare intentional non-HTTP protocols explicitly. `allowedProtocols="*"` and
`allowNoHost=true` are opt-in exceptions, not Brix defaults.

Write regular-expression constraints with `regex("pattern", "flags")`, such as
`@type=string(matches=regex("^[0-9a-f]{7,40}$", "i"))`. Plain or `/pattern/` strings are deprecated;
pass an unwrapped pattern to `regex()`.

Unquoted values shaped like function calls are parsed as resolvers such as `op(...)`, and malformed
ones fail validation rather than becoming literal text. Quote literal values that contain
parentheses, for example `RELEASE_LABEL="beta (2)"`.

## Redaction and optional Varlock features

Use the root `@redact` decorator to configure log redaction; `@redactLogs` is a deprecated alias
that warns. Commands Brix runs through Varlock (`brix env run`, `brix dev`, `brix build --stage`,
and `brix test --env`) redact sensitive values from child stdout/stderr by default whenever that
stream is piped or redirected, as in CI; interactive terminals are not rewritten. Machine-readable
output that echoes a secret is therefore rewritten in CI. Set `# @redact(stdout=false)` in the
schema to disable stdout/stderr redaction. Do not exempt secrets from redaction merely
to remove warnings. Brix does not redact browser traces or arbitrary application artifacts.

Leave Varlock's default environment injection enabled. Brix commands and script `loadEnv()` read
that injected payload; Varlock's encrypted environment freezing is not a Brix transport and does not
replace exact-version deployment snapshots. Type generation never contacts providers.

## Generate and consume types

Brix refreshes schema-only types before dev, test, build, run, exec, watch, and dlx workflows, even when those commands do not resolve providers. Generate explicitly after schema edits:

```sh
brix env types

```

Commit `src/env.generated.d.ts`, but never edit it. `brix check`, `brix doctor`, and `brix ci` report missing or stale output without writing it.

At a workspace root, use the member-scoped repair printed by doctor, for example
`brix env#apps/backend types`. Plain `brix env types` runs only inside an application; it does not
regenerate every member. A missing member declaration produces one environment-type diagnostic.

`src/env.server.ts`

```ts
"use server";

import { createEnv } from "brix/env";
import type { CoercedEnvSchema } from "./env.generated.d.ts";

export const env = createEnv<CoercedEnvSchema>();

```

Server setup passes this declaration to `defineBrixServer`, and request modules read validated values from `c.env`. Do not read `process.env` in features or import environment values into islands. Application rules remain in `.env.schema`.
Doctor also rejects destructuring `env` from the global process, imported process bindings, and
statically traceable `const` aliases in application runtime modules. Locally shadowed names are
not treated as Node's process. This is bounded static detection, not whole-program data-flow
analysis: it does not follow mutable aliases or computed property names that require evaluation.
Test modules and scripts outside `src/` retain their environment-access exemption; scripts should
use the explicit typed loader described in [environment loading](/docs/environment-loading.md).

Validation has two stages. Varlock applies application types, requiredness, and constraints when
loading or uploading values. At runtime, `createEnv` checks the snapshot envelope and allowed keys,
then deeply freezes its values; the TypeScript generic does not repeat the authored schema's
validation. Ship code and generated types with a snapshot produced from the matching schema, and
restrict snapshot writes to the trusted publication workflow.

If `check` reports stale types, run `brix env types`, review the generated diff, and commit it with
the schema change. If loading fails, fix the reported key or provider authentication rather than
weakening `@required` or marking a secret public to make the command pass.

Next, select authored values for commands and tests in [loading environments](/docs/environment-loading.md).
