Environment Variables

The env map declares app-owned environment variables. Each value is a string (shorthand for default value) or an object.

Field	Type	Required	Description
`default`	`string \| number \| boolean`	no	Default value
`description`	`string`	no	Human description (supports markdown)
`label`	`string`	no	Short label for CLI prompts
`required`	`boolean`	no	App cannot start without this value
`example`	`string`	no	Example value showing expected format
`generator`	`enum`	no	Auto-generate: `secret`, `uuid`, `port`
`sensitive`	`boolean`	no	Store in a secrets manager

A bare scalar (PORT: "8080") is shorthand for { default: "8080" }. Booleans and numbers work too.

When generator: secret is set, sensitive: true is implied — the platform should store the generated value in a secrets manager and mask it in logs and UI.

env:
  PORT:
    default: "8080"
  API_KEY:
    required: true
    description: "Third-party API key"
    example: "sk-live-abc123..."
  SESSION_SECRET:
    generator: secret
    sensitive: true

Real-world examples: See how WordPress and Gitea wire environment variables from resources. Browse all apps →

Value provenance

Every declared env value has exactly one provenance class, determined by precedence: generator: → expression default: → literal default: → user-supplied. A generator: or a supplied default: satisfies required: — required: true alongside either asserts the value is non-empty at runtime; it does not change the class. Platform obligations follow the class:

Minted (generator: present) — generated once, then preserved across redeploys and identity changes. generator: port is exempt: a port is an allocation, not an identity, so it is re-allocated rather than preserved.
Derived (expression default: over platform-resolved inputs like $app.url or resource properties) — recomputed when its inputs change, unless an operator has overridden the deployed value.
Author default (literal default:) — a starting value chosen by the file author; ordinary per-environment config the orchestrator may override.
User-supplied (no generator, no default) — never supplied or altered by the platform, whether required: true or a bare declaration whose presence activates a feature.

set_env entries classify the same way: expression wirings are derived; literal wirings are deliberately constant and passed through verbatim — overriding one breaks the declared resource wiring rather than configuring the app. Whether a deployed value is currently the resolved default, an operator override, or a once-generated secret is orchestrator state, never recorded in the file. See DESIGN.md D-49 for the full rationale.