Environment System

Manages environment variables through configurable storage backends.

Overview

The environment system separates storage from access:

• Storages - Where values are stored (OS, files, memory)
• Variables - Named references to values in storages

Variables can be referenced by:

• Public name - The variable field value (must be unique across the system)
• Entry ID - Full namespace:name reference

If you don't want a variable to be publicly accessible by name, omit the variable field.

Entry Kinds

Storage Backends

Memory Storage

Volatile in-memory storage.

- name: runtime_env
  kind: env.storage.memory

File Storage

Persistent storage using .env file format (KEY=VALUE with # comments).

- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700

OS Storage

Read-only access to operating system environment variables.

- name: os_env
  kind: env.storage.os

Always read-only. Set operations return PERMISSION_DENIED.

Static Storage

Read-only storage with values defined directly in configuration. Values are baked into the entry and cannot be changed at runtime. Useful for public configuration constants that ship with a module or pack.

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"

Always read-only. Set operations return PERMISSION_DENIED.

Router Storage

Chains multiple storages. Reads search in order until found. Writes go to first storage only.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primary (writes here)
    - app.config:file      # Fallback
    - app.config:os        # Fallback

Variables

Variables provide named access to storage values.

- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  readonly: false

Variable Naming

Variable names must contain only: a-z, A-Z, 0-9, _

Access Patterns

# Public variable - accessible by name "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Private variable - accessible only by ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Placeholder Interpolation

Registered variables are pulled into entry configuration with ${env:NAME} placeholders, resolved centrally at decode time against this registry. Any string field in an entry's data may reference a variable this way.

NAME is a registered variable's public name or its entry ID (registry-id form with dots/colons, e.g. app.env:tls_cert). It is not a raw OS environment variable: an OS value is reachable only when an env.storage.os-backed variable is registered under that name.

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}

A field whose entire value is a single placeholder takes the variable's typed value (coerced to bool/int/float when a typed default is given); a placeholder mixed with surrounding text interpolates into a string. A variable's own default is honored before the placeholder's inline |default. A reference that resolves to nothing and has no default fails decoding.

Resolution happens at decode time only: the stored registry entry keeps the raw placeholders, so resolved secrets never appear in registry.get results or persisted state. Entries referencing ${env:...} automatically order after the env storages and variables they depend on at boot.

Errors

Runtime Access

• env module - Lua runtime access

See Also

• Security Model - Access control for environment variables
• Configuration Guide - Application configuration patterns