Express agent command-line installation (agent-only installer)

3 minute read

The agent software must be installed on each machine you intend to use with CloudBees Flow. An agent is a CloudBees Flow component that runs on a machine resource. The agent executes CloudBees Flow job steps, monitors step progress, and records job completion information.

Certain CloudBees Flow installers allow you to perform installations as a non-root user or a user without sudo privileges. To determine whether a particular installer has an option to run in this mode, see Installing Without Root/sudo or Administrator Privileges .

Review Before You Install CloudBees Flow before performing this procedure.

  1. Download the appropriate agent-only installer file.

    For details, see CloudBees Flow Installer Files .

  2. Enter the following command to make the installer file executable:

    chmod +x <agent_installer_file>

    For example, enter:

    chmod +x CloudBeesFlowAgent-x64-

  3. Choose one of the following commands to begin the installation:

    • For installations with root or sudo privileges, enter:


    • For installations with root or sudo privileges and the X Window System, override the installer GUI by entering:

      ./<agent_installer_file> --mode console

    • For non-root/non- sudo installations, enter:

      ./<agent_installer_file> --mode console --nonRoot
  4. After the confirmation prompt, continue the installation by entering y.

The following prompt appears:

Specify the type of setup you would like to perform: expressAgent or advanced. [expressAgent]

  1. Press Enter to accept expressAgent. The following prompt appears:

Discover the plugins directory from a remote CloudBees Flow server? [n/Y]

  1. Enter y if you want the agent machine to have access to the plugins directory. You should allow access to the plugins directory so agents have access to collections of features, third-party integrations, or third-party tools.

The plugins directory on the CloudBees Flow server must be “shared” before the agent machine can use “discover” to find the directory. For more information, see Universal Access to the Plugins Directory .

The following prompt appears:

Create a resource for the installed agent on a remote CloudBees Flow server? [n/Y]

  1. Enter y to automatically create a resource object for the agent on a remote CloudBees Flow server. This option is recommended to save time configuring new CloudBees Flow resources for existing CloudBees Flow servers.

The following prompt appears:

Register as trusted agent? [y/N]

Making an agent trusted restricts the agent to one CloudBees Flow server. The agent will not respond to incoming communication from any other CloudBees Flow server. This is useful when you want to create a secure production environment, but generally not needed for test or development systems.


You can run gateways without trusted agents. However, you should use gateways with trusted agents to prevent security issues in the firewall between zones connected by a gateway.

There are exceptions to using gateways without trusted agents:

  • The firewall between two zones is not required in your environment or is needed only to protect the CloudBees Flow server.

  • There is a specific reason to use gateways without trusted agents, such as a requirement to prevent unauthorized users from accessing your network. All incoming traffic from the internet is routed to a data center through a load balancer, and the load balancer routes the traffic to the appropriate machine in your network.

    1. Choose one of the following options:

      • If a gateway is used to communicate with the CloudBees Flow server, you must select y. This option allows you to create a trusted network connection between the agent and server under the same certificate authority. This will allow the agent and the CloudBees Flow server to communicate across the network.

      • If there is no gateway between the agent and CloudBees Flow server, enter n.

        If you deviated from the recommended agent options, you will see variations in the installation options that appear on your system.

For root or sudo installations, The following prompt appears:

+ Specify the user the agent will run as. [] . (Root or sudo installations) Enter a user name. This is the user who owns the CloudBees Flow agent process. For example, you might enter build.

The user/group that the agent runs as must have permission to write to the $INSTALL_DIRECTORY/log directory. If you specify root, enter y when the following confirmation appears:

It is not recommended to use the 'root' user for running the agent process. Please confirm if you would like to proceed [y/N]

The following prompt appears:

Specify the group the agent will run as. []

  1. (Root or sudo installations) Enter a Group Name. This is the group that owns the CloudBees Flow agent process. For example, you might enter build.

    CloudBees Flow is installed on the machine. When the installation completes successfully, a prompt that contains the line " CloudBees Flow <version> was successfully installed! " appears.

  2. For non-root/non- sudo Linux installations, configure autostart for the CloudBees Flow agent service.