cleveragents-core/docs/reference/config_resolution.md

Configuration Resolution Chain

CleverAgents uses a multi-level configuration resolution chain that determines the effective value for each configuration key. This document describes the resolution order, all registered configuration keys, their types, defaults, and environment variable mappings.

Resolution Order

Values are resolved from highest to lowest priority. The first level that provides a non-None value wins:

Priority	Level	Description
1	CLI flag	Value passed explicitly via --key=value on the CLI
2	Env var	Environment variable (CLEVERAGENTS_<SECTION>_<KEY>)
3	Project scope	Per-project override in [project."<name>"] TOML table
4	Global config	Value in ~/.cleveragents/config.toml
5	Default	Built-in default from the key registry

Example

$ export CLEVERAGENTS_CORE_LOG_LEVEL=WARNING
$ agents config set core.log_level DEBUG      # writes to global config
$ agents config get core.log_level
# -> WARNING (env var wins over global config)

Environment Variable Convention

All registered keys map to environment variables following the pattern:

CLEVERAGENTS_<SECTION>_<KEY>

Where <SECTION> and <KEY> are uppercased. For example:

• core.log_level -> CLEVERAGENTS_CORE_LOG_LEVEL
• plan.max_retries -> CLEVERAGENTS_PLAN_MAX_RETRIES
• provider.temperature -> CLEVERAGENTS_PROVIDER_TEMPERATURE

Configuration Keys

core.* — Core Runtime

Key	Type	Default	Env Var	Project-Scopable	Description
core.log_level	str	INFO	CLEVERAGENTS_CORE_LOG_LEVEL	Yes	Logging verbosity level
core.debug_enabled	bool	false	CLEVERAGENTS_CORE_DEBUG_ENABLED	Yes	Enable debug mode
core.env	str	development	CLEVERAGENTS_CORE_ENV	Yes	Runtime environment name
core.data_dir	str	data	CLEVERAGENTS_CORE_DATA_DIR	Yes	Base data directory path
core.database_url	str	sqlite:///cleveragents.db	CLEVERAGENTS_CORE_DATABASE_URL	No	Primary database URL
core.server_host	str	0.0.0.0	CLEVERAGENTS_CORE_SERVER_HOST	No	Server bind host
core.server_port	int	8080	CLEVERAGENTS_CORE_SERVER_PORT	No	Server bind port

plan.* — Plan Execution

Key	Type	Default	Env Var	Project-Scopable	Description
plan.auto_apply	bool	false	CLEVERAGENTS_PLAN_AUTO_APPLY	Yes	Auto-apply plans on completion
plan.max_retries	int	3	CLEVERAGENTS_PLAN_MAX_RETRIES	Yes	Maximum plan retry count
plan.timeout_seconds	int	300	CLEVERAGENTS_PLAN_TIMEOUT_SECONDS	Yes	Plan execution timeout in seconds

provider.* — LLM Provider

Key	Type	Default	Env Var	Project-Scopable	Description
provider.default_provider	str	""	CLEVERAGENTS_PROVIDER_DEFAULT_PROVIDER	No	Default LLM provider name
provider.default_model	str	""	CLEVERAGENTS_PROVIDER_DEFAULT_MODEL	No	Default LLM model name
provider.temperature	float	0.7	CLEVERAGENTS_PROVIDER_TEMPERATURE	Yes	LLM sampling temperature
provider.max_tokens	int	4096	CLEVERAGENTS_PROVIDER_MAX_TOKENS	Yes	Max tokens per LLM response

sandbox.* — Sandbox Isolation

Key	Type	Default	Env Var	Project-Scopable	Description
sandbox.strategy	str	git_worktree	CLEVERAGENTS_SANDBOX_STRATEGY	Yes	Default sandbox strategy
sandbox.auto_cleanup	bool	true	CLEVERAGENTS_SANDBOX_AUTO_CLEANUP	Yes	Auto-clean sandbox after use
sandbox.max_age_hours	int	48	CLEVERAGENTS_SANDBOX_MAX_AGE_HOURS	Yes	Max sandbox age before cleanup

context.* — Context Management

Key	Type	Default	Env Var	Project-Scopable	Description
context.max_files	int	100	CLEVERAGENTS_CONTEXT_MAX_FILES	Yes	Maximum context files per session
context.max_tokens	int	128000	CLEVERAGENTS_CONTEXT_MAX_TOKENS	Yes	Maximum context token window
context.auto_include_gitignore	bool	true	CLEVERAGENTS_CONTEXT_AUTO_INCLUDE_GITIGNORE	Yes	Auto-include gitignore in context filtering

index.* — Vector Store Indexing

Key	Type	Default	Env Var	Project-Scopable	Description
index.enabled	bool	false	CLEVERAGENTS_INDEX_ENABLED	Yes	Enable vector-store indexing
index.backend	str	faiss	CLEVERAGENTS_INDEX_BACKEND	Yes	Vector store backend name
index.embedding_model	str	fake	CLEVERAGENTS_INDEX_EMBEDDING_MODEL	Yes	Embedding model for indexing
index.embedding_dimension	int	1536	CLEVERAGENTS_INDEX_EMBEDDING_DIMENSION	Yes	Embedding vector dimension

Validation Rules

Unknown Keys

Attempting to get or set an unregistered key will produce an actionable error:

ValueError: Unknown configuration key: 'bogus.key'.
Valid keys include: context.auto_include_gitignore, context.max_files, ...

Type Mismatches

Values are coerced to the registered type. If coercion fails, an actionable error is raised:

TypeError: Type mismatch for key 'core.server_port': expected int,
got str with value 'not_a_number'.

Boolean coercion accepts: true/false, 1/0, yes/no (case-insensitive).

TOML File Location

The global configuration file is stored at:

~/.cleveragents/config.toml

Parent directories are created automatically on first write. Project-scoped overrides live under [project."<name>"] tables within the same file.

Verbose Mode

When --verbose is passed to config get, the full resolution chain is displayed, showing which level provided (or could provide) the value:

$ agents config get core.log_level --verbose
Key:    core.log_level
Value:  INFO
Source: default

Resolution chain (highest -> lowest priority):
  cli_flag       -> (not set)
  env_var        -> (not set)  [CLEVERAGENTS_CORE_LOG_LEVEL]
  project        -> (not set)
  global         -> (not set)  [~/.cleveragents/config.toml]
  default        -> INFO       <-- active