Bamboo remote agent installation guide

Before you begin

Before you begin installing remote agents, there are a few questions you need to answer. 

Do you need to install a remote agent?

See Agents and capabilities to understand how remote agents interact with your Bamboo server.

Do you have sufficient agent licenses?

See Bamboo licensing for details.

Does your system meet the minimum requirements?

See Supported platforms.

Do you have a supported version of Java installed on the agent machine?

See Supported platforms.

Are you upgrading your version of Bamboo?

  • If you're upgrading Bamboo from a release earlier than 6.10 to a release that's also earlier than 6.10, your remote agents will be upgraded automatically along with Bamboo. 
  • If you're upgrading Bamboo from a release earlier than 6.10 to 6.10 or later, manually upgrade your remote agents to make sure that the Tanuki wrapper is also updated and the wrapper.conf file is successfully recreated.

    Bamboo 6.10 comes with an updated Tanuki wrapper that fixes some known issues but is not updated automatically and must be reinstalled.

  • To upgrade agents manually...
    1. Stop the original agent.
    2. Backup the BAMBOO_AGENT_HOME/conf/wrapper.conf file.
    3. Remove the BAMBOO_AGENT_HOME/conf directory.
    4. Download a new Remote Agent JAR from your Bamboo Server: http://<BAMBOO_URL>/admin/agent/addRemoteAgent.action.
    5. Launch the remote agent. T
      This will create new
      wrapper.conf file. If you want to re-enact your custom configuration in that file, you can do it now.
  • If you're upgrading Bamboo from a release earlier than 8.0 to 8.0 or later and you're also upgrading the Java version on your remote agents from 8 to 11, either update the wrapper configuration manually or download a new remote agent JAR from your upgraded Bamboo and reinstall the wrapper.

    To reinstall wrapper
    1. Stop the original agent.
    2. Backup the BAMBOO_AGENT_HOME/conf/wrapper.conf file.
    3. Remove the BAMBOO_AGENT_HOME/conf directory.
    4. Download a new Remote Agent JAR from your Bamboo Server: http://<BAMBOO_URL>/admin/agent/addRemoteAgent.action.
    5. Launch the remote agent. This will create new wrapper.conf file. If you want to re-enact your custom configuration in that file, you can do it now.
    To update wrapper.conf
    1. Stop the original agent.
    2. Open wrapper configuration file - BAMBOO_AGENT_HOME/conf/wrapper.conf
    3. Set the value of the wrapper.java.version.max property to 11.
    4. Start the agent.
  • If you're upgrading Bamboo from an earlier version to versions 8.2–9.3, download a new Remote Agent JAR from your upgraded Bamboo and reinstall the wrapper.

    To reinstall wrapper
    1. Stop the original agent.
    2. Back up the BAMBOO_AGENT_HOME/conf/wrapper.conf file.
    3. Remove the BAMBOO_AGENT_HOME/conf directory.
    4. Download a new Remote Agent JAR from your Bamboo Server at http://<BAMBOO_URL>/admin/agent/addRemoteAgent.action.
    5. Launch the remote agent. This will create new wrapper.conf file. If you want to re-enact your custom configuration in that file, you can do it now.

Mixing operating systems between Bamboo Server and Remote Agents is supported and possible.

For example, you can connect a Linux based Remote Agent to a Windows Bamboo Server or a Windows Remote Agent to a Linux based Bamboo Server.

The only requirement is that it's running on a supported Operating System and Java version:

Note that you can run multiple Bamboo agents on the same machine – you just need to provide a separate home directory for each agent installation.

1. Enable remote agent support

  1. From the Bamboo header select  > Build resources > Agents.
  2. Select either Enable Remote Agent Support or Disable Remote Agent Support.

For more information on enabling and disabling remote agent support, see Disabling and enabling remote agents support.

 2. Download and install the remote agent

  1. Create a directory on the agent machine (e.g. bamboo-agent-home) to serve as the Bamboo agent home for the remote agent.
  2. From the Bamboo header select  > Build resources > Agents.
  3. The Agents screen displays showing the lists of all local agents and all remote agents that currently exist on your Bamboo system.
  4. If not already enabled, select the Enable remote agent support link.
  5. Select Install remote agent. The Installing a remote agent screen will display.
  6. Select DOWNLOAD Remote Agent JAR and save the JAR file to the directory on the agent machine that you created above.
  7. Copy the command under Running a Remote Agent to the clipboard for use in Step 3 that follows.

3. Launch the remote agent

Once installed, run the remote agent by executing the command line obtained above. This command will look something like this:

java -jar atlassian-bamboo-agent-installer-X.X-SNAPSHOT.jar http://bamboo-host-server:8085/bamboo/agentServer/

Where X.X represents your Bamboo version number.

If you are having issues launching the agent, then take a look at our troubleshooting guide.

The name of the .jar file (for example, atlassian-bamboo-agent-installer-5.4-SNAPSHOT.jar) will vary depending on the version of Bamboo you are running.


You can run the remote agent with a number of additional command line parameters. Configuration options include remote agent data storage, capability detection and logging, suppression of self-signed certificate and running without the Remote Agent Supervisor or with different start-up commands.

See Additional remote agent options for more information.

4. Configure the remote agent's capabilities

All remote agents feature a capability that can be defined. Examples include an executable, such as Maven, a JDK, a DVCS client or a custom capability. They typically define the path to an executable that has already been installed, and must be defined in Bamboo before Bamboo or its agents can make use of them.

Capabilities can be defined specifically for an agent, or shared between all local or all remote agents.

See Configuring capabilities for more on defining capabilities.

Last modified on Oct 25, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.