# DimOS GlobalConfig Fields Precedence Order: 5-Level Configuration Cascade

> Understand DimOS GlobalConfig field precedence. Learn the 5-level configuration cascade: defaults, .env, env vars, blueprint overrides, and CLI flags. Discover the order that wins.

- Repository: [Dimensional/dimos](https://github.com/dimensionalOS/dimos)
- Tags: architecture
- Published: 2026-03-15

---

**DimOS resolves every `GlobalConfig` field through a strict five-level cascade where later sources overwrite earlier ones, following the order: built-in defaults → `.env` file → environment variables → blueprint overrides → CLI flags.**

In the `dimensionalOS/dimos` robotics framework, configuration management relies on `GlobalConfig` to centralize runtime settings. Understanding the exact precedence order for these fields ensures predictable behavior when multiple configuration sources conflict.

## The Five-Level Precedence Hierarchy

DimOS uses `pydantic-settings` to merge configuration sources in [`dimos/core/global_config.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/core/global_config.py). The framework evaluates sources from most general to most specific.

### Level 1: Built-in Defaults

The base layer consists of hard-coded values in [`dimos/core/global_config.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/core/global_config.py) at lines 30-35. These defaults establish safe fallbacks when no other source provides a value.

```python

# From dimos/core/global_config.py

simulation = False  # Default value if nothing else is set

```

If you do not override this field via any other mechanism, `GlobalConfig.simulation` remains `False`.

### Level 2: `.env` File Configuration

Next, DimOS loads values from a `.env` file located in the repository root. The `GlobalConfig` class uses `SettingsConfigDict(env_file=".env")` to trigger this loading, as implemented at lines 58-62 in [`dimos/core/global_config.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/core/global_config.py).

Create a `.env` file to establish project-wide settings:

```text
DIMOS_SIMULATION=true
DIMOS_VIEWER=foxglove

```

These values overwrite the built-in defaults but remain vulnerable to higher-precedence sources.

### Level 3: Environment Variables

Variables prefixed with `DIMOS_` that are present in the process environment overwrite both defaults and `.env` values. According to [`docs/usage/cli.md`](https://github.com/dimensionalOS/dimos/blob/main/docs/usage/cli.md) (lines 44-49), DimOS automatically maps environment variables to `GlobalConfig` fields.

```bash
export DIMOS_SIMULATION=false
export DIMOS_VIEWER=rerun-web

```

Running `dimos` commands in this shell session uses these environment values instead of the `.env` file settings.

### Level 4: Blueprint-Level Overrides

Robot blueprints can inject specific `GlobalConfig` instances that apply only to that blueprint. As documented in [`docs/usage/cli.md`](https://github.com/dimensionalOS/dimos/blob/main/docs/usage/cli.md) (lines 48-50), you pass a `GlobalConfig` object via the `global_config` parameter in blueprint definitions.

```python
from dimos.core.global_config import GlobalConfig
from dimos import autoconnect

my_blueprint = autoconnect(
    robot_stack,
    global_config=GlobalConfig(simulation=True)  # Blueprint-specific override

)

```

These overrides affect only the single blueprint instance, leaving global defaults untouched for other runs.

### Level 5: CLI Flags (Highest Precedence)

Command-line options such as `--simulation` or `--no-simulation` represent the final authority. As noted in [`docs/usage/cli.md`](https://github.com/dimensionalOS/dimos/blob/main/docs/usage/cli.md) (lines 44-51), CLI flags always win regardless of what earlier sources specify.

```bash
dimos --no-simulation run unitree-go2

```

Even if your `.env` file sets `DIMOS_SIMULATION=true` and the blueprint enables simulation, this flag forces the value to `False`.

## Inspecting and Overriding Configuration Values

### Verify the Active Configuration

To see which source supplied each final value, use the built-in inspection command:

```bash
dimos show-config

```

This outputs each `GlobalConfig` field alongside its source classification: **default**, **.env**, **env-var**, **blueprint**, or **CLI**.

### Temporary Environment Overrides

For one-off runs without modifying files, prepend environment variables directly:

```bash
DIMOS_VIEWER=rerun dimos run unitree-go2

```

### Persistent Project Configuration

Store shared settings in the repository root `.env` file to affect all team members using the project, while reserving CLI flags for individual run customization.

## Summary

- **DimOS applies a five-level cascade** for `GlobalConfig` resolution: built-in defaults → `.env` file → environment variables → blueprint overrides → CLI flags.
- **Source files** implementing this logic include [`dimos/core/global_config.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/core/global_config.py) (defaults and pydantic-settings configuration) and [`docs/usage/cli.md`](https://github.com/dimensionalOS/dimos/blob/main/docs/usage/cli.md) (precedence documentation).
- **CLI flags possess ultimate authority**, making them ideal for temporary runtime adjustments without code changes.
- **Blueprint overrides provide isolation**, affecting only the specific robot stack instance they configure.
- **Use `dimos show-config`** to audit which configuration source is active for any field.

## Frequently Asked Questions

### How can I determine which configuration source is currently active for a specific field?

Run `dimos show-config` in your terminal. This command displays the resolved value for every `GlobalConfig` field and labels the source that provided it—whether default, `.env`, environment variable, blueprint, or CLI flag.

### Do blueprint-level overrides affect other blueprints running concurrently?

No. Blueprint overrides are isolated to the specific blueprint instance where you define them. According to the source code in [`dimos/core/global_config.py`](https://github.com/dimensionalOS/dimos/blob/main/dimos/core/global_config.py), each blueprint receives its own configuration context, ensuring that overrides in one robot stack do not leak to others.

### What naming convention must environment variables follow to override GlobalConfig fields?

Environment variables must use the `DIMOS_` prefix followed by the uppercase field name. For example, the field `simulation` maps to `DIMOS_SIMULATION`, and `viewer` maps to `DIMOS_VIEWER`.

### Can I prevent CLI flags from overriding specific blueprint configurations?

No. The precedence order is immutable by design. CLI flags always occupy the highest precedence level (level 5) and will overwrite any value set by blueprints, environment variables, or `.env` files. If you need to lock a configuration, you must remove the CLI flag parsing for that specific field in your deployment setup.