> ## 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.

# Installation

AgentCompass currently needs to be installed from source. This page explains how to prepare the host environment,
install AgentCompass, configure optional dependencies, and verify local or remote execution environments.

## Prerequisites

Before installation, prepare Git, CA certificates, download and archive-extraction tools, and native build tools for
your operating system:

<Tabs>
  <Tab title="Linux / WSL">
    On Ubuntu, Debian, and Ubuntu-based WSL distributions:

    ```bash theme={"system"}
    sudo apt-get update
    sudo apt-get install -y \
      build-essential \
      ca-certificates \
      curl \
      git \
      unzip \
      wget
    ```

    For other Linux distributions, use the appropriate package manager to install these tools. See the
    [official Git installation page](https://git-scm.com/downloads/) for Git-specific instructions.
  </Tab>

  <Tab title="macOS">
    macOS includes `curl`, `unzip`, and CA certificates. Use the Xcode Command Line Tools for native builds and
    [Homebrew](https://brew.sh/) for Git and wget:

    ```bash theme={"system"}
    xcode-select --install
    brew install git wget
    ```
  </Tab>

  <Tab title="Windows">
    Windows includes `curl.exe`, and PowerShell provides archive extraction through `Expand-Archive`. Install Git with
    WinGet:

    ```powershell theme={"system"}
    winget install --id Git.Git --exact --source winget
    ```

    Alternatively, install [Scoop](https://scoop.sh/) using its official instructions, then manage Git and wget with:

    ```powershell theme={"system"}
    scoop install git wget
    ```

    Use WSL 2 for workloads that require `/bin/sh`, POSIX paths, or Unix build tools.
  </Tab>
</Tabs>

Before running an evaluation, you also need model endpoint credentials and a supported execution environment. See
[Supported Operating Systems](#supported-operating-systems) for details.

After completing these steps, verify that Git and `curl` are available:

```bash theme={"system"}
git --version
curl --version
```

## Install AgentCompass

Install AgentCompass in an isolated virtual environment. Do not mix `uv`, `pip`, and `conda` in the same environment
unless you understand how each tool resolves dependencies.

First, clone the repository and enter the project directory:

```bash theme={"system"}
git clone https://github.com/open-compass/AgentCompass.git
cd AgentCompass
```

Then choose one installation method:

<Tabs>
  <Tab title="uv (recommended)">
    Install `uv` using the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/).

    Linux, WSL, or macOS:

    ```bash theme={"system"}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    uv python install 3.12
    uv venv --python 3.12
    source .venv/bin/activate
    uv pip install -e .
    ```

    Windows PowerShell:

    ```powershell theme={"system"}
    winget install --id=astral-sh.uv -e
    uv python install 3.12
    uv venv --python 3.12
    .venv\Scripts\Activate.ps1
    uv pip install -e .
    ```

    If the host does not already have Python 3.12, the commands above install and manage a Python 3.12 runtime through
    `uv`. See the [uv Python installation guide](https://docs.astral.sh/uv/guides/install-python/).
  </Tab>

  <Tab title="pip + venv">
    First install Python 3.12 from the [official Python downloads](https://www.python.org/downloads/).

    Linux, WSL, or macOS:

    ```bash theme={"system"}
    python3.12 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```

    Windows PowerShell:

    ```powershell theme={"system"}
    py -3.12 -m venv .venv
    .venv\Scripts\Activate.ps1
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```
  </Tab>

  <Tab title="Conda">
    After installing and initializing [Conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/), run:

    ```bash theme={"system"}
    conda create -n agentcompass python=3.12
    conda activate agentcompass
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```
  </Tab>
</Tabs>

**Verify the installation:** With the environment activated, confirm that the Python version is correct and the
AgentCompass CLI is available:

```bash theme={"system"}
python --version
agentcompass --version
```

To browse results with [`agentcompass view`](/en/user_guide/using_agentcompass/cli/view) from a source install, also install Node.js 20.19+ or 22.12+; the viewer frontend is built automatically on the first run.

## Install Optional Dependencies as Needed

The base installation includes only AgentCompass's core dependencies; you do not need to preinstall every component
dependency. When an evaluation starts, AgentCompass checks dependencies as needed for the selected benchmark and
harness.

If you plan to run SWE-bench or use mini-swe-agent locally on the host, you can preinstall both sets of optional
dependencies:

```bash theme={"system"}
uv pip install -e ".[swebench,mini-swe-agent]"
```

If a dependency is missing, AgentCompass stops and displays the appropriate installation command. Install the
dependency, then rerun the original command. You can also enable automatic installation for trusted built-in
components:

```bash theme={"system"}
agentcompass run <benchmark> <harness> <model> --auto-install-dependencies
```

<Note>
  `--auto-install-dependencies` installs dependencies only in the host Python environment that runs AgentCompass. It
  does not modify Docker, Daytona, or Modal environments; their dependencies come from the task image or environment
  configuration.
</Note>

To prepare an offline environment or review all optional dependencies, see
[Dependency Management](/en/user_guide/using_agentcompass/dependencies).

## Execution Environments

Prepare the execution environment required by each selected benchmark. Running multiple benchmarks may require
different environments.

See [Environments in the User Guide](/en/user_guide/modules/environments/overview) for selection guidance, parameters,
resources, and network configuration.

<Tabs>
  <Tab title="host_process">
    `host_process` runs commands as normal subprocesses and uses the real host filesystem, installed tools, permissions,
    and network access. It starts quickly but provides no isolation, and results can vary with host state.

    Linux and WSL 2 are fully supported. Use macOS only for lightweight or service-backed workloads explicitly supported
    by the benchmark documentation, because packages, utilities, paths, and evaluation scripts can still depend on
    Linux. Native Windows is unsupported because the current implementation and common workflows rely on `/bin/sh`,
    POSIX paths, permissions, and signals.

    <Warning>
      Do not use `host_process` for an untrusted agent or one that can execute commands. It can read, modify, or delete
      files available to your user account and start processes directly on the host.
    </Warning>

    See the [`host_process` guide](/en/user_guide/modules/environments/providers/host_process) for parameters and safety limits.
  </Tab>

  <Tab title="Docker">
    Docker creates an isolated container for each task; its dependencies and filesystem layout come from the task image.
    It is more consistent than `host_process`, but the first run may need to pull a large image.

    AgentCompass supports local Docker on Linux and WSL 2. Follow the
    [Docker Engine installation guide](https://docs.docker.com/engine/install/), then verify:

    ```bash theme={"system"}
    docker version
    docker info
    docker run --rm hello-world
    ```

    If Docker works only with `sudo`, follow the
    [Linux post-installation guide](https://docs.docker.com/engine/install/linux-postinstall/) to configure access:

    ```bash theme={"system"}
    sudo groupadd docker
    sudo usermod -aG docker "$USER"
    newgrp docker
    docker run --rm hello-world
    ```

    If the `docker` group was created during installation, skip the first command.

    <Warning>
      Membership in the `docker` group grants root-level privileges on the host.
    </Warning>

    On WSL 2, choose one topology: install Docker Engine inside the WSL distribution, or enable Docker Desktop
    [WSL integration](https://docs.docker.com/desktop/features/wsl/). Do not maintain both daemons. Keep the checkout in
    the WSL Linux filesystem, such as `~/code/AgentCompass`, rather than under `/mnt/c/`.

    See the [Docker guide](/en/user_guide/modules/environments/providers/docker) for registry credentials, smoke tests, and
    parameters.
  </Tab>

  <Tab title="Daytona">
    Daytona runs tasks in cloud sandboxes and supports Linux, WSL, Windows, and macOS. Create an account and an
    [API key](https://www.daytona.io/docs/en/api-keys/) with sandbox access, then set the credential:

    ```bash theme={"system"}
    export DAYTONA_API_KEY="..."
    ```

    Windows PowerShell:

    ```powershell theme={"system"}
    $env:DAYTONA_API_KEY = "..."
    ```

    API endpoints, `target`, and organization settings are optional. Never commit credentials to the repository. See the
    [Daytona guide](/en/user_guide/modules/environments/providers/daytona) for complete setup.
  </Tab>

  <Tab title="Modal">
    Modal runs tasks in cloud sandboxes and supports Linux, WSL, Windows, and macOS. Create an account, then follow the
    [user account setup guide](https://modal.com/docs/guide/modal-user-account-setup) or
    [service user guide](https://modal.com/docs/guide/service-users) to create a token and set the credentials:

    ```bash theme={"system"}
    export MODAL_TOKEN_ID="..."
    export MODAL_TOKEN_SECRET="..."
    ```

    Windows PowerShell:

    ```powershell theme={"system"}
    $env:MODAL_TOKEN_ID = "..."
    $env:MODAL_TOKEN_SECRET = "..."
    ```

    The Modal CLI can also store credentials in `~/.modal.toml`. Never commit tokens to the repository. See the
    [Modal guide](/en/user_guide/modules/environments/providers/modal) for complete setup.
  </Tab>
</Tabs>

## Supported Operating Systems

AgentCompass is installed on your host machine. Evaluation tasks can run directly on that host, in a local Docker
container, or in a cloud sandbox:

| Operating system | Install and use AgentCompass | host\_process | Local Docker | Daytona / Modal |
| - | - | - | - | - |
| Linux | Yes | Yes | Yes | Yes |
| WSL 2 ([see installation](https://learn.microsoft.com/windows/wsl/install)) | Yes | Yes | Yes | Yes |
| Windows | Yes | No | No | Yes |
| macOS | Yes | Limited | No | Yes |

<Warning>
  Even if Docker Desktop can start Linux containers on native Windows or macOS, AgentCompass does not currently
  support Docker Desktop as a local benchmark environment. Use WSL 2, Daytona, or Modal for coding, terminal, and
  other Linux-specific workloads.
</Warning>

## Troubleshooting

| Symptom | Check |
| - | - |
| Python version mismatch | Run `python --version`; recreate the environment with Python `>=3.12`. |
| `agentcompass: command not found` | Activate the environment, reinstall editable mode, or use `uv run agentcompass`. |
| `uv`, `pip`, or dataset downloads fail | Check DNS, proxy, CA certificates, and HTTPS access to the package index. |
| `Cannot connect to the Docker daemon` | Start Docker and run `docker info` from the same Linux or WSL shell. |
| Docker works in Windows but not WSL | Enable Docker Desktop integration for that WSL 2 distribution. |
| Repository operations are slow in WSL | Move the checkout from `/mnt/c/` to the WSL Linux filesystem. |
| Daytona startup fails | Verify the API key and optional API endpoint or `target`. |
| Modal authentication fails | Run `modal token info` and verify the active workspace credentials. |
| Optional dependency installation fails in a restricted sandbox | Preinstall it in the task image or prepare it before network access is disabled. |


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