Skip to main content

​
Overview

AIOX uses a three-level configuration hierarchy to manage framework, project, and local settings. This architecture ensures framework stability while allowing project-specific customization.

​
Configuration Hierarchy

AIOX implements a three-tier configuration system:
​
Level 1
Framework
Framework Configuration - Read-only settings shipped with the AIOX npm package
  • File: framework-config.yaml
  • Location: .aiox-core/
  • Mutability: Read-only (framework source)
  • Git Status: Committed to framework
  • Reference: ADR-PRO-002 — Configuration Hierarchy
​
Level 2
Project
Project Configuration - Team-shared settings committed to repository
  • File: project-config.yaml
  • Location: .aiox-core/
  • Mutability: Editable by project maintainers
  • Git Status: Committed to project repository
  • Purpose: Project-specific customizations shared across team
​
Level 3
Local
Local Configuration - Developer-specific settings (not committed)
  • File: local-config.yaml
  • Location: .aiox-core/
  • Mutability: Fully editable
  • Git Status: Ignored (.gitignore)
  • Purpose: Personal developer preferences and secrets

​
Configuration Resolution

Settings are resolved using a merge strategy with precedence: 
local-config.yaml (highest priority)
    ↓ overrides
project-config.yaml
    ↓ overrides
framework-config.yaml (lowest priority)

​
Core Configuration File

The core-config.yaml file is the legacy single-file configuration that predates the three-tier system. It contains all configuration in one place.
​
core-config.yaml
object
Location: .aiox-core/core-config.yamlThis file is being gradually migrated to the three-tier system. New projects should use framework-config.yaml and project-config.yaml instead.See Core Config Reference for complete schema.

​
File Locations

​
Configuration Directory
string
required
.aiox-core/ - Root directory for all configuration files
​
Available Files
array
  • core-config.yaml - Legacy unified configuration
  • framework-config.yaml - Level 1 (Framework)
  • project-config.yaml - Level 2 (Project)
  • local-config.yaml - Level 3 (Local, git-ignored)
  • local-config.yaml.template - Template for local configuration

​
Configuration Loading

AIOX loads configuration in the following order:
  1. Framework defaults from framework-config.yaml
  2. Project overrides from project-config.yaml
  3. Local overrides from local-config.yaml (if exists)
  4. Runtime environment variables (highest priority)

​
Best Practices

  • Only modify framework-config.yaml for framework-wide changes
  • Document all changes in ADRs
  • Ensure backward compatibility
  • Use semantic versioning for breaking changes
  • Customize via project-config.yaml for team settings
  • Never commit local-config.yaml
  • Document project-specific configurations
  • Use local-config.yaml.template for team onboarding
  • Use local-config.yaml for personal preferences
  • Copy from local-config.yaml.template to start
  • Never commit secrets or API keys
  • Keep local overrides minimal

​
Migration from Core Config

If your project uses core-config.yaml, you can migrate to the three-tier system: 
# Run migration script (when available)
aiox config migrate

# Manual migration:
# 1. Review core-config.yaml
# 2. Split framework defaults → framework-config.yaml
# 3. Move project settings → project-config.yaml
# 4. Move personal settings → local-config.yaml
Reference: ADR-PRO-002 — Configuration Hierarchy

Build docs developers (and LLMs) love

Get started for freeTalk to us