Configuration — Alius Docs

Configuration Overview

Alius stores project configuration in .alius/config/. Each file handles a specific configuration domain, and you can manage them interactively through the TUI’s embedded /config, /model, and /init commands, or by editing files directly.

File	Purpose
`config.toml`	Main configuration — runtime metadata, default model/provider, UI, Session, logging
`providers.toml`	Provider definitions, compatible routing layer, local model library, Base URL and API Key
`model.toml`	Plan/Execute/Review three-role model assignment
`soul.toml`	Agent identity (Agent Card compatible configuration)
`tools.toml`	Built-in/MCP/plugin/workflow tools, timeouts, confirmation, and registration settings
`permissions.toml`	File system, Shell, network, memory, project document, and remote A2A permissions
`protocol.toml`	Protocol interface enablement and event/command settings
`mcp.json`	MCP server declarations

Initialization progress is saved in .alius/runtime/init-state.toml (separate from configuration files) and is not part of the configuration files.

Provider Configuration

providers.toml is one of the most critical configuration files, containing provider definitions, a compatible routing layer, and a local model library.

Built-in Providers

Alius includes the following built-in providers:

Provider ID	Product Label	OpenAI Compatible Base URL	Anthropic Compatible Base URL
`bigmodel`	BigModel GLM (Zhipu Coding Plan)	`https://open.bigmodel.cn/api/coding/paas/v4`	`https://open.bigmodel.cn/api/anthropic`
`xiaomi_mimo`	Xiaomi MiMo (Token Plan)	`https://api.xiaomimimo.com/v1`	`https://api.xiaomimimo.com/anthropic`
`deepseek`	DeepSeek	`https://api.deepseek.com`	`https://api.deepseek.com/anthropic`

Provider Configuration Structure

[router]
strategy = "tier"
default = "medium"

[tiers.light]        # Plan Model tier
model = "glm-4-flash"
provider = "bigmodel"

[tiers.medium]       # Execute Model tier
model = "glm-4-plus"
provider = "bigmodel"

[tiers.high]         # Review Model tier
model = "glm-4"
provider = "bigmodel"

[providers.bigmodel]
kind = "openai"
base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
api_key_env = "BIGMODEL_API_KEY"
enabled = true

Local Model Library

The [[model_library.models]] section in providers.toml stores project-level model entries, managed by /model and assigned by /config.

Each model entry contains:

Field	Description
`id`	Stable entry ID, typically derived from provider and model name
`display_name`	User-facing model label
`provider`	Provider identifier matching `[providers.<name>]`
`base_url`	Base URL used by this model entry
`model_name`	Provider-native model ID sent to the runtime
`reasoning_note`	Compatibility note
`enabled`	Whether this entry is selectable

Example:

[[model_library.models]]
id = "bigmodel_glm-4-flash"
display_name = "GLM-4-Flash"
provider = "bigmodel"
base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
model_name = "glm-4-flash"
enabled = true

Model Assignment

model.toml stores the three-role model assignment architecture:

schema_version = 1

[assignment]
plan = "bigmodel_glm-4-flash"      # Plan Model
execute = "bigmodel_glm-4-plus"     # Execute Model
review = "bigmodel_glm-4"          # Review Model

Role	Description	Compatibility Mapping
Plan Model	Used for goal understanding and plan generation	`tiers.light`
Execute Model	Used for plan execution and tool calls	`tiers.medium` + active legacy model
Review Model	Used for result review and quality assessment	`tiers.high` + legacy review_model

/config only assigns roles from enabled local model library entries. Manual entry of model names, Base URLs, or API Keys is not allowed during the assignment flow.

API Key Management

API Keys are provided through:

Environment variables (recommended) — Specify api_key_env in the provider configuration, e.g., BIGMODEL_API_KEY
Interactive input — Enter directly during the /model or /init add flow (plaintext, supports pasting)

After saving, API Keys are not displayed in session output or model details. A successful /init model fetch also writes the API Key to the active runtime settings, ensuring Bypass/Chat mode does not report a missing api_key.

Modifying Configuration

Interactive Configuration

Use slash commands within the workspace:

/config          # Open configuration center (Models/Language/Soul)
/model           # Open model pool manager
/init            # Re-run the initialization wizard

All configuration operations take effect immediately, with no save button needed.

Command Line

alius config show        # Display current configuration
alius config validate    # Validate configuration integrity
alius config credential  # Manage credentials

Global Parameters

alius --model gpt-4o-mini --provider openai

Configuration Loading

Alius’s configuration loading process:

Searches upward from the current directory for .alius/ to find the project root
Loads configuration files from .alius/config/
Missing files use default values
Generates a ProjectConfigSnapshot
Builds the runtime view RuntimeConfigView (containing provider, tool, permission, Shell Gate, logging, Session, and Soul configuration)

Security Notes

API Keys are referenced through environment variables and never stored in plaintext in configuration files
The config show command masks sensitive values
File writes and Shell operations are controlled by permissions.toml and Shell Gate