agentcompass config

agentcompass config shows values merged from configuration files or lists the fields accepted by components in the current installation.

agentcompass config {show|docs}

config show

config show merges built-in defaults with loaded configuration files and prints the result as YAML or JSON:

agentcompass config show [OPTIONS]

Without component selectors, the command prints only runtime and execution. Use --benchmark, --harness, or --env to include selected component configurations. Each selector accepts multiple space-separated IDs and can also be repeated.

agentcompass config show \
  --config examples/configs/swebench_verified.yaml \
  --benchmark swebench_verified \
  --harness mini_swe_agent \
  --env docker

Option	Description
--config <path>	Load an additional YAML or JSON override file. Repeatable; later files take precedence.
--benchmark <id>...	Show built-in defaults and file overrides for the selected Benchmark.
--harness <id>...	Show built-in defaults and file overrides for the selected Harness.
--env <id>...	Show built-in defaults and file overrides for the selected Environment.
--format yaml|json	Select the output format. The default is yaml.

These selectors only decide which component configurations are printed; they do not change the components used by an evaluation. Other component sections in the configuration file are not shown automatically.

config show redacts fields that look like common keys, tokens, or passwords. Private endpoints and other sensitive values may not be detected, so inspect the output before sharing or committing it.

config docs

config docs shows the declared fields, types, built-in defaults, and descriptions for one registered component:

agentcompass config docs KIND COMPONENT-ID

For example:

agentcompass config docs benchmark swebench_verified
agentcompass config docs harness mini_swe_agent
agentcompass config docs env docker

Positional argument	Value	Description
KIND	benchmark, harness, or env	Component kind.
COMPONENT-ID	A registered component ID	Component to inspect. Find IDs with agentcompass list.

This command displays the schema declared in component code and does not load configuration files. Long default values are abbreviated in the terminal table. Use config show to inspect the merged file result; sensitive fields remain redacted. Parameters for the model under test are outside the scope of config docs; see Configure a Model.

Configuration File Structure

Configuration files store defaults that can be reused across runs. The following top-level sections are supported:

Configuration path	Contents
runtime	Runtime settings such as result and data directories, evaluation time limit, logging, progress, and Environment provider limits.
execution	Shared run controls, per-task timeouts, artifact settings, and result analysis.
benchmarks.<id>	Configuration fields for a Benchmark.
harnesses.<id>	Configuration fields for a Harness.
environments.<id>	Configuration fields for an Environment.

Write component fields directly below their ID; do not add a nested params mapping. Run configuration loaded with --config does not support a top-level models section. Provide the model under test through agentcompass run arguments, agentcompass launch orchestration requests, or the Python SDK.

The repository’s examples/configs/swebench_verified.yaml shows how these sections fit together. It selects one SWE-bench Verified sample for checking configuration and the execution environment. Remove benchmarks.swebench_verified.sample_ids to select the complete dataset.

After setting MODEL_NAME, MODEL_BASE_URL, and MODEL_API_KEY, run the following command from the repository root:

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --config examples/configs/swebench_verified.yaml \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"

Override Order

config show merges values in the following order, from lowest to highest priority:

1. Built-in runtime, execution, and component defaults.
2. $XDG_CONFIG_HOME/agentcompass/config.yaml, or ~/.config/agentcompass/config.yaml when XDG_CONFIG_HOME is not set.
3. The nearest config.yaml found by searching upward from the current working directory.
4. Explicit --config files. The option is repeatable, and later files override earlier files.

Ordinary mappings are merged recursively; higher-priority scalar and list values replace lower-priority values. Shared Environment fields use the rules below. Missing implicit user or project files are ignored, while a missing explicitly specified file is an error.

config show stops at these configuration-file layers. During an evaluation, explicit run/launch CLI options, orchestration-file fields, and Python SDK arguments take precedence over configuration files. For a single evaluation request, dependency auto-installation can also be overridden by AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES; launch does not read that variable. A Recipe then adapts each concrete task’s execution plan. It usually preserves compatible explicit image and resource settings, but it can still adjust workspace, network, or execution settings required by the Benchmark or Harness. The config show output is therefore not a complete execution plan for a particular evaluation.

Layered Environment Overrides

Configuration files retain their layer boundaries until a provider is selected. Explicit CLI, Python SDK, and orchestration request overrides use the same field rules:

Shared fields	Merge rule
resources, run_resources, evaluation_resources	Resource quantities and model constraints override field by field; omitted or null fields inherit lower-priority values. A higher-priority gpu: 0 clears the inherited gpu_type. ignore_gpu_type: true clears the inherited model constraint while preserving the GPU count.
setup, evaluation_setup	Override field by field; omitted or null fields inherit lower-priority values.
baseline_network_policy, evaluation_baseline_network_policy, run_network_policy, evaluation_network_policy	A non-null higher-priority policy replaces the corresponding lower-priority policy entirely, without inheriting its host lists. Omission or null means inherit.
env_variables, run_env_variables, evaluation_env_variables, evaluation_environment_env_variables	Merge by variable name; higher-priority values replace matching names.
evaluation_environment_mode, require_startup_env	A non-null higher-priority value replaces the lower-priority value. An explicit false also overrides require_startup_env. Omission or null means inherit.

For example, lower-priority resources of gpu: 1, gpu_type: A100 overridden by gpu: 0 no longer retain a model constraint. Likewise, overriding an allowlist policy with no-network does not retain the old host list.

A conflict within one layer is different from a cross-layer override. Declaring both gpu: 0 and gpu_type: A100 in one resource declaration, or no-network and nonempty allowed_hosts in one policy, is an error even if a higher-priority override follows. Conflicting declarations are checked per layer; full effective-value validation happens after overrides are merged. File-layer conflict errors identify the source file.

Loading checks configuration structure. Only selected providers undergo the field parsing and semantic checks above; obsolete fields or invalid resource values for unused providers do not block the evaluation. config show displays the merged result; it does not replace final effective-value and provider-capability validation during evaluation.

Environment Variables and Secrets

Configuration files support whole-field ${VAR} environment references. For example:

environments:
  docker:
    setup:
      image: ${TASK_IMAGE}

Environment references in ordinary configuration fields are resolved after configuration files are merged. Ordinary fields under environments are resolved per file layer after a provider is selected, before applying the merge rules above. An unset variable resolves to an empty string. Interpolation within a larger value, such as https://${HOST}/api, is not supported.

For example, if a lower-priority setup.image references an unset TASK_IMAGE, a valid higher-priority image can replace that empty value. If the final image is still empty, evaluation rejects it.

Task environment-variable mappings are an exception: references in env_variables and its phase-specific mappings are retained during configuration loading and resolved in the execution process after task and request overrides are merged. Missing required variables without a fallback cause an error rather than silently injecting empty strings.

Do not commit keys, tokens, or private endpoints. If a private configuration file must contain sensitive values, exclude it from version control.