clearml-docs/docs/clearml_agent/clearml_agent_execution_env.md

title
Execution Environments

ClearML Agent has two primary execution modes: Virtual Environment Mode and Docker Mode.

Virtual Environment Mode

In Virtual Environment Mode, the agent creates a virtual environment for the experiment, installs the required Python packages based on the task specification, clones the code repository, applies the uncommitted changes and finally executes the code while monitoring it. This mode uses smart caching so packages and environments can be reused over multiple tasks (see Virtual Environment Reuse).

ClearML Agent supports working with one of the following package managers:

• pip (default)
• conda
• poetry

To change the package manager used by the agent, edit the package_manager.type field in the of the clearml.conf. If extra channels are needed for conda, add the missing channels in the package_manager.conda_channels field in the clearml.conf.

:::note Using Poetry with Pyenv Some versions of poetry (using install-poetry.py) do not respect pyenv global.
If you are using pyenv to control the environment where you use ClearML Agent, you can:

• Use poetry v1.2 and above (which fixes this issue)
• Install poetry with the deprecated get-poetry.py installer :::

Docker Mode

:::note notes

• Docker Mode is only supported in Linux.
• Docker Mode requires docker service v19.03 or higher installed.
• If your machine requires root permissions to run Docker, the ClearML Agent in Docker Mode must also run with root permissions. :::

When executing the ClearML Agent in Docker mode, it will:

1. Run the provided Docker container
2. Install ClearML Agent in the container
3. Execute the Task in the container, and monitor the process.

ClearML Agent uses the provided default Docker container, which can be overridden from the UI.

:::tip Setting Docker Container via UI You can set the docker container via the UI:

1. Clone the experiment
2. Set the Docker in the cloned task's Execution tab > Container section
3. Enqueue the cloned task

The task will be executed in the container specified in the UI. :::

All ClearML Agent flags (such as --gpus and --foreground) are applicable to Docker mode as well.

• To execute ClearML Agent in Docker mode, run:

  clearml-agent daemon --queue <execution_queue_to_pull_from> --docker [optional default docker image to use]
  

• To use the current clearml-agent version in the Docker container, instead of the latest clearml-agent version that is automatically installed, pass the --force-current-version flag:

  clearml-agent daemon --queue default --docker --force-current-version
  

• For Kubernetes, specify a host mount on the daemon host. Do not use the host mount inside the Docker container. Set the environment variable CLEARML_AGENT_K8S_HOST_MOUNT. For example:

  CLEARML_AGENT_K8S_HOST_MOUNT=/mnt/host/data:/root/.clearml