Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The configuration system in M31 Autonomous (M31A) provides a robust framework for managing provider credentials, model selection, workflow behavior, and UI customization. It is designed with a "security-first" approach, utilizing the OS keychain for sensitive data and a TOML-based file system for general settings.
M31A utilizes a multi-layered configuration resolution strategy, ensuring that settings can be inherited from environment variables, local project contexts, or global user settings. This allows the agent to adapt its behavior—such as switching between different LLM providers like OpenRouter, Zen, or Nvidia—based on the specific requirements of a coding task.
Configuration Architecture
The architecture of M31A's configuration is centered around a hierarchical loading process and a strict permission system for tool execution.
Configuration Resolution Order
M31A resolves configuration values in a specific order to allow for flexible overrides:
- Environment Variables: Highest priority for runtime overrides.
- OS Keychain: Secure storage for API keys (Linux dbus, macOS Keychain, Windows Credential Manager).
- TOML Configuration File: Local or global settings stored in
~/.m31a/config.toml.
Sources: README.md:129-132, CONTRIBUTING.md:46-49
Component Diagram
The following diagram illustrates the relationship between the configuration loader and other system components.
The Config Loader aggregates settings from multiple storage backends to initialize core managers.
Sources: README.md:395-440, CONTRIBUTING.md:52-75
Core Configuration Sections
The configuration is organized into functional blocks within the config.toml file.
Provider and Model Settings
M31A supports triple provider redundancy with automatic fallback. Users can define default models for specific workflow phases.
| Option | Type | Description |
|---|---|---|
provider.default | string | Primary LLM gateway (e.g., "openrouter", "zen", "nvidia"). |
provider.auto_fallback | boolean | Enables switching providers if the primary is unavailable. |
model.auto_arbitrage | boolean | Recommends the cheapest model meeting quality requirements. |
model.token_ema_alpha | float | Smoothing factor for token estimation calibration. |
Sources: README.md:213-225, README.md:270-285
Workflow Features
Workflow behavior is highly configurable through feature toggles, allowing users to enable or disable specific quality gates.
[features]
plan_research = true # Pre-plan research step
plan_check = true # Revision loops for plans
plan_security_gate = true # Security heuristics check
execute_loop_detect = true # Tool-call loop detection
ship_changelog = true # Auto-generate session changelogs
Sources: README.md:295-315
Tool Configuration and Permissions
M31A implements a strict permission system to gate the execution of the 18 built-in tools, particularly those involving shell access or file modifications.
Permission Levels
Tools are categorized by risk level, which dictates how the configuration handles their execution:
- Normal Tools: Gated by a token-bucket rate limiter (20 burst / 10 sustained).
- Dangerous Tools: (e.g.,
git reset,rm) Require explicit permission and have stricter limits (5 burst / 2 sustained).
Sources: README.md:380-385, internal/engine/workflow/prompts/tool-use.md:8-13
Tool Security Model
The permission system acts as a security boundary before any tool execution occurs.
Sources: README.md:470-485, scripts/validate-release.sh:255-265
Project-Specific Configuration
M31A detects project context to apply specialized configuration logic, such as for Next.js website builds.
Website Build Configuration
When a project is classified with a "website" scope, specific design system tokens and component rules are applied.
- Color Tokens: Defined in
app/globals.cssas CSS custom properties. - Typography: Configured via
next/font/google. - UI Library: Enforced use of
shadcn/uicomponents from@/components/ui/.
Sources: internal/engine/workflow/prompts/website-build.md:15-30, internal/engine/workflow/prompts/intent-classify.md:25-30
Validation and Maintenance
The configuration system is validated through automated scripts to ensure all required components and phase constants are present.
Release Validation
M31A uses scripts/validate-release.sh to verify:
- Config Loader: Presence of
internal/config/loader.goandvalidateConfigfunction. - Phase Constants: Definitions for all 7 phases (Initialize to Ship) in
internal/types/types.go. - Keychain Backends: Availability of platform-specific keychain implementations.
Sources: scripts/validate-release.sh:305-325, scripts/validate-release.sh:340-350
Summary
The configuration system in M31A serves as the operational backbone of the agent, balancing flexibility with security. By separating sensitive API keys into the OS keychain and exposing technical toggles in a structured TOML format, M31A allows developers to fine-tune the autonomous workflow while maintaining a secure local environment.