Environment Variables
Environment variable governance — SBX_ prefix, resolution order, .env patterns, atomic generation
Tags
Overview
Purpose
Environment variable governance — SBX_ prefix, resolution order, .env patterns, atomic generation
Rules
ENV-001: All SBX framework ENV vars use SBX_ prefix.
Namespace prefix prevents collision with system or third-party variables. SBX_ is scannable and filterable.
Verification: Grep: SBX framework env vars all start with SBX_. No unprefixed framework variables.
ENV-002: Scripts declare accepted ENV vars in DEFAULTS dict at file top.
Declared defaults are self-documenting. A reader sees all configuration knobs without tracing code paths.
Verification: Script review: DEFAULTS or equivalent declaration at top of file.
ENV-003: Resolution order: CLI args > ENV vars > DEFAULTS.
CLI args are most specific (user intent), env vars are deployment-specific, defaults are universal. This precedence matches user expectation.
Verification: Test: CLI arg overrides env var, env var overrides default.
ENV-004: SBX_ROOT: Framework root directory. Default: cwd().
All path resolution anchors to SBX_ROOT. Without it, scripts break when run from non-root directories.
Verification: Script: paths computed relative to SBX_ROOT, not hardcoded.
ENV-005: SBX_SCHEMAS_DIR: Path to schemas directory. Default: .framework/core.
Schema location must be overridable for testing with alternate schema directories.
Verification: Schema operations use SBX_SCHEMAS_DIR, not hardcoded path.
ENV-006: SBX_OUTPUT_DIR: Default output directory. Default: output.
Output location must be overridable for CI, testing, and deployment scenarios.
Verification: Output operations use SBX_OUTPUT_DIR.
ENV-007: SBX_RUNTIME_DIR: Runtime execution directory. Default: .runtime.
Runtime state (task tracking, ID counters) needs a known location that's separate from source code.
Verification: Runtime operations use SBX_RUNTIME_DIR.
ENV-008: SBX_PIPELINES_DIR: Process definitions directory. Default: .framework/lifecycle.
Lifecycle pipeline location must be overridable for testing alternate step configurations.
Verification: Pipeline operations use SBX_PIPELINES_DIR.
ENV-009: Use .env files for docker-compose environment variables. Never commit .env files with local paths or secrets.
.env files contain machine-specific paths and secrets. Committing them leaks credentials and breaks on other machines.
Verification: .gitignore includes .env. No .env files in git history.
ENV-010: .env files with local paths/secrets must be .gitignored. Provide .env.example template in version control.
.env.example shows the structure without exposing values. New developers can copy and fill in their values.
Verification: .env.example exists alongside .gitignored .env files.
ENV-011: Provide .env.example template in version control showing expected structure without actual values.
Self-documenting setup reduces onboarding friction. Developers know exactly which variables to set.
Verification: .env.example contains all required variable names with placeholder values.
ENV-012: All env vars sourced from adapter CLI commands (client-adapter, port-adapter, etc). Never hardcode values.
Adapters are the single source of truth for configuration. Hardcoded values drift from adapter state.
Verification: Code review: env var values come from sbx commands, not inline strings.
ENV-013: Generate .env to temp file first, then atomic move to prevent partial file states.
Partial .env writes cause container startup failures with missing variables. Atomic move ensures all-or-nothing.
Verification: Script review: .env generation uses temp file + mv pattern.
ENV-014: Validate .env completeness before using. Fail fast with clear error messages if required vars missing.
Missing env vars cause cryptic runtime failures. Upfront validation gives clear error messages with the variable name.
Verification: Script/service startup includes env validation step before proceeding.