DimOS GlobalConfig Fields Precedence Order: 5-Level Configuration Cascade

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. 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 at lines 30-35. These defaults establish safe fallbacks when no other source provides a value.

# 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.

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

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 (lines 44-49), DimOS automatically maps environment variables to GlobalConfig fields.

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 (lines 48-50), you pass a GlobalConfig object via the global_config parameter in blueprint definitions.

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 (lines 44-51), CLI flags always win regardless of what earlier sources specify.

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:

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:

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 (defaults and pydantic-settings configuration) and 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}