> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentcompass config

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

```bash theme={"system"}
agentcompass config {show|docs}
```

## `config show`

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

```bash theme={"system"}
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.

```bash theme={"system"}
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:

```bash theme={"system"}
agentcompass config docs KIND COMPONENT-ID
```

For example:

```bash theme={"system"}
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`](/en/user_guide/using_agentcompass/cli/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](/en/user_guide/modules/models/overview).

## 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](/en/user_guide/using_agentcompass/run_controls#scale-concurrency-safely). |
| `execution` | Execution settings such as task concurrency, retries, environment retention, 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`](https://github.com/open-compass/AgentCompass/blob/main/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:

```bash theme={"system"}
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](/en/user_guide/using_agentcompass/dependencies#automatic-installation) can also be
overridden by `AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES`; `launch` does not read that variable. A
[Recipe](/en/user_guide/other_features/recipes) 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:

```yaml theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.