Configuration - Ubiquex

ubx reads all stack configuration from .xcl files. There is no ubx.yaml for XCL stacks — engine, backend, AI settings, scan settings, and history settings are all declared in the XCL source.

The resolution chain

Every configuration field is resolved through a four-level chain. Lower levels set defaults; higher levels override.

workspace {}         ← universal defaults for all stacks
workspace { match {} }  ← workspace scoped to matching stacks
context {}           ← named group a stack opts into
meta {} inside stack {}  ← per-stack overrides (highest priority)

Fields that are not additive (engine, runtime, backend type, AI model, scan severity) follow last-wins: the most specific block that declares the field wins. Fields that are additive (tags, hooks) are merged: all levels contribute. A stack that declares no meta {} and belongs to no context {} receives only the universal workspace {} values, or ubx’s built-in defaults if no workspace block is present.

What goes where

workspace — workspace-wide defaults

Use workspace {} for settings that apply to every stack in the compilation unit unless a more specific block overrides them.

workspace {
    engine  = "native"
    runtime = "xcl"

    backend s3 {
        bucket = "my-state-bucket"
        key    = "platform"
    }

    ai {
        enabled = true
        model   = "claude-haiku-4-5"
    }

    scan {
        enabled  = true
        severity = "high"
    }

    history {
        enabled = true
    }

    tags {
        project    = "platform"
        managed_by = "ubx"
    }
}

A workspace {} block with a match {} sub-block applies only to stacks whose effective labels match. A universal workspace {} (no match {}) applies first; a label-scoped workspace {} overlays it.

context — group configuration

Use context {} to declare a named configuration group that multiple stacks opt into. A context sits between the workspace and per-stack overrides in the resolution chain.

context prod_eu {
    labels {
        env    = "prod"
        region = "eu-west-1"
    }
    backend s3 {
        bucket = "state-eu-prod"
        key    = "platform/prod"
    }
    scan {
        severity = "critical"
    }
}

A stack opts in via meta { context = "prod_eu" }. All fields declared in the context override the workspace for that stack.

meta inside stack — per-stack overrides

Use meta {} for settings specific to a single stack. meta {} is the highest priority in the chain — it overrides everything.

stack "payments" {
    meta {
        context = "prod_eu"
        ai {
            enabled = false
        }
    }

    // stack body...
}

meta {} can both opt the stack into a context {} and declare per-stack field overrides. Fields declared directly in meta {} override the context.

The one exception: API keys

API keys are secrets, not source configuration. The Anthropic API key is never read from .xcl files. Set it via environment variable:

export UBX_AI_API_KEY="sk-ant-..."

Or via ai.api_key in ubx.yaml (deprecated path — supported for backward compatibility, but prefer the env var). The env var always takes priority. AI features are enabled when UBX_AI_API_KEY is set and the workspace ai { enabled = true } is declared (or no workspace block disables it). If the API key is absent, AI features are silently skipped regardless of what the workspace block declares.

Runtime environment overrides

Some settings can be overridden at runtime via environment variables without touching source files. These are useful for CI and per-deployment customisation.

Environment variable	What it overrides
`UBX_AI_API_KEY`	Anthropic API key — always takes priority over `ai.api_key` in ubx.yaml
`PULUMI_BACKEND_URL`	State backend URL — overrides the `backend {}` block in the workspace
`UBX_TELEMETRY_ENDPOINT`	Telemetry collection endpoint — overrides the built-in default

PULUMI_BACKEND_URL is useful when the same source files must deploy to different backends in different environments (e.g., local development vs. CI vs. production). The XCL backend {} block is lower priority than this env var. UBX_TELEMETRY_ENDPOINT is intended for self-hosted telemetry. The built-in default points to Ubiquex infrastructure; set this variable to redirect telemetry to your own collector.

History storage

Apply history is controlled by the history {} sub-block in workspace {}, context {}, or meta {}:

workspace {
    history {
        enabled = true
    }
}

When enabled, ubx writes ubx-history.json to the same storage location as the Pulumi state file. For S3, GCS, and Azure Blob backends, history is stored in the same bucket/container alongside the stack state. For the local file backend, history is stored at .ubx/ubx-history.json in the stack directory. History is enabled by default when no history {} block is declared. Declare history { enabled = false } to opt out. The history {} block can appear at any level of the resolution chain. A meta {} override takes priority:

// Workspace enables history for all stacks...
workspace {
    history { enabled = true }
}

// ...but this stack opts out
stack "scratch" {
    meta {
        history { enabled = false }
    }
    // ...
}

Migration guide: from ubx.yaml

If you have an existing ubx.yaml, the table below maps each key to its new location in a workspace {} block.

ubx.yaml key	New location
`backend: s3://bucket/state`	`workspace { backend s3 { bucket = "bucket" key = "state" } }`
`backend: file:///abs/path`	`workspace { backend local { path = "/abs/path" } }`
`backend: https://api.pulumi.com`	`workspace { backend pulumi { } }`
`history.enabled: false`	`workspace { history { enabled = false } }`
`ai.enabled: true`	`workspace { ai { enabled = true } }`
`ai.model: claude-opus-4-8`	`workspace { ai { model = "claude-opus-4-8" } }`
`ai.features.plan_summary: true`	`workspace { ai { features { plan_summary = true } } }`
`ai.features.cost_estimate: false`	`workspace { ai { features { cost_estimate = false } } }`
`scan.enabled: true`	`workspace { scan { enabled = true } }`
`scan.severity: critical`	`workspace { scan { severity = "critical" } }`
`ai.api_key: "sk-ant-..."`	Set `UBX_AI_API_KEY` env var — do not put secrets in source files
`telemetry.endpoint: "..."`	Set `UBX_TELEMETRY_ENDPOINT` env var

Fields project:, stack:, and default_tags: remain in ubx.yaml and continue to be read from there. Only the fields listed above have moved to XCL workspace blocks.

A complete workspace block replacing a typical ubx.yaml

// workspace.xcl — replaces the stack-level keys that were in ubx.yaml

workspace {
    backend s3 {
        bucket = "my-state-bucket"
        key    = "platform/prod"
        encryption {
            provider = "awskms"
            key      = "alias/pulumi-secrets"
        }
    }

    ai {
        enabled = true
        model   = "claude-haiku-4-5"
        features {
            plan_summary  = true
            cost_estimate = true
        }
    }

    scan {
        enabled  = true
        severity = "high"
    }

    history {
        enabled = true
    }
}

Place this file in any .xcl file in your stack directory (e.g. workspace.xcl). ubx discovers all .xcl files in the directory — there is no required filename for workspace {} blocks.

​The resolution chain

​What goes where

​workspace — workspace-wide defaults

​context — group configuration

​meta inside stack — per-stack overrides

​The one exception: API keys

​Runtime environment overrides

​History storage

​Migration guide: from ubx.yaml

​A complete workspace block replacing a typical ubx.yaml

​See also