Installing and Configuring Trains Agent

Install Trains Agent to run worker daemons for experiment execution, as well as use its other features such as building worker environments without experiment execution, and initializing the Trains Agent configuration using the setup wizard, and listing the configuration.

Trains and Trains Agent use the same configuration file, but not all of the same configuration options. Depending upon your operating system, the configuration file is:

  • Linux - ~/trains.conf
  • Mac - $HOME/trains.conf
  • Windows - \User\<username>\trains.conf

Trains Agent uses a cache folder to cache pip packages, apt packages and cloned repositories. The default cache folder is ~/.trains.

Installing Trains Agent

Execute the following command:

pip install trains_agent

Configuring Trains Agent

After installing Trains Agent, if you are using your own locally-hosted Trains Server, you must configure Trains Agent by either:

  • Creating a Trains configuration file using our interactive setup.
  • Editing the existing Trains configuration file, if one exists.

    Why would a Trains configuration file already exist?

    Trains and Trains Agent use the same configuration file, but not all the same configuration options. If you previously installed and configure Trains Agent, you may have an existing configuration file.

If you are using our Trains demo server (https://demoapp.trains.allegro.ai/dashboard), no configuration is required because Trains Agent works with the demo server by default.

To configure Trains Agent:

  1. Open a terminal session in Linux or a command prompt session in Microsoft Windows.
  2. In your terminal session, run the setup wizard by executing the following command: 
    trains-agent init
    If the setup wizard's response indicates you already have a configuration file, you must edit it. The wizard does not edit or overwrite existing configuration files.
  3. At the prompt, enter the URL for your Trains Server web server.

    You must use a secure protocol, "https". Do not use "http".

    Enter the url of the trains-server’s Web service, for example: http://localhost:8080

Web Application Host configured to: []
  4. Enter the API server (press Enter to accept the default value which is based on your previous response): 
    API Host configured to:
  5. Enter the file server (press Enter to accept the default value which is based on your previous response): 
    File Store Host configured to:
    The wizard responses with your configuration and directs you to your Trains Server's, Trains Web-App to create Trains credentials. 
    TRAINS Hosts configuration:
Web App: <your web server url>
API: <your api server url>
File Store: <your file server url>

Please create new credentials using the web app: <your web server url>/profile
In the Admin page, press "Create new credentials", then press "Copy to clipboard"

Paste credentials here:
  6. At the command prompt Paste credentials here:, copy and paste the Trains credentials you create as follows:
    1. Click the hyperlink for your Trains Server, Trains Web-App.
    2. If you are not logged in, then login.

      Why would a login not be required?

      If your Trains Server is not configured for web login authentication, no login is required. You can add web login authentication, see Configuring Web Login Authentication on the "Configuring Trains Server" page.

    3. Click the PROFILE page.
    4. Click Create new credentials.
    5. Click Copy to clipboard.
    6. In your terminal session, paste your credentials and press Enter.

    The configuration is verified. The location of your configuration file appears.

    Verifying credentials ...
Credentials verified!

  7. Enter your Git user name and password.

    Enter git username for repository cloning (leave blank for SSH key authentication): []
Enter password for user '<user_name>':

    Trains Agent configuration is completed.

    New configuration stored in /home/user/trains.conf
TRAINS-AGENT setup completed successfully.

Your Trains Agent configuration file is saved. Its location depends upon your operating system:

  • Linux - ~/trains.conf
  • Mac - $HOME/trains.conf
  • Windows - \User\<username>\trains.conf

Editing the Configuration File

If a Trains configuration file already exists, edit it and add Git credentials and an agent section containing your Trains Agent settings.

To edit a Trains configuration file:

  1. Open your Trains configuration file for editing. Depending upon your operating system, it is:
    • Linux - ~/trains.conf
    • Mac - $HOME/trains.conf
    • Windows - \User\<username>\trains.conf
  2. After the api section add the following for your Git credentials, replacing . 
    # Set GIT user/pass credentials
# leave blank for GIT SSH credentials
agent.git_user="<your_git_username>"
agent.git_pass="<your_git_password>"
  3. After the Git credentials (previous step) add the following agent section (it contains default values for options) 
    agent {
    # unique name of this worker, if None, created based on hostname:process_id
    # Override with os environment: TRAINS_WORKER_ID
    # worker_id: "trains-agent-machine1:gpu0"
    worker_id: ""

    # worker name, replaces the hostname when creating a unique name for this worker
    # Override with os environment: TRAINS_WORKER_NAME
    # worker_name: "trains-agent-machine1"
    worker_name: ""

    # Set GIT user/pass credentials for cloning code, leave blank for GIT SSH credentials.
    # git_user: ""
    # git_pass: ""

    # select python package manager:
    # currently supported pip and conda
    # poetry is used if pip selected and repository contains poetry.lock file
    package_manager: {
        # supported options: pip, conda
        type: pip,

        # virtual environment inheres packages from system
        system_site_packages: false,

        # install with --upgrade
        force_upgrade: false,

        # additional artifact repositories to use when installing python packages
        # extra_index_url: ["https://allegroai.jfrog.io/trainsai/api/pypi/public/simple"]
        extra_index_url: []

        # additional conda channels to use when installing with conda package manager
        conda_channels: ["defaults", "conda-forge", "pytorch", ]
    },

    # target folder for virtual environments builds, created when executing experiment
    venvs_dir = ~/.trains/venvs-builds

    # cached git clone folder
    vcs_cache: {
        enabled: true,
        path: ~/.trains/vcs-cache
    },

    # use venv-update in order to accelerate python virtual environment building
    # Still in beta, turned off by default
    venv_update: {
        enabled: false,
    },

    # cached folder for specific python package download (used for pytorch package caching)
    pip_download_cache {
        enabled: true,
        path: ~/.trains/pip-download-cache
    },

    translate_ssh: true,
    # reload configuration file every daemon execution
    reload_config: false,

    # pip cache folder used mapped into docker, for python package caching
    docker_pip_cache = ~/.trains/pip-cache
    # apt cache folder used mapped into docker, for ubuntu package caching
    docker_apt_cache = ~/.trains/apt-cache

    default_docker: {
        # default docker image to use when running in docker mode
        image: "nvidia/cuda"

        # optional arguments to pass to docker image
        # arguments: ["--ipc=host", ]
    }

    # cuda versions used for solving pytorch wheel packages
    # should be detected automatically. Override with os environment CUDA_VERSION / CUDNN_VERSION
    # cuda_version: 10.1
    # cudnn_version: 7.6
}

Your Trains Agent configuration file is saved.

Next Steps