Skip to end of metadata
Go to start of metadata

This page describes how to install the Bamboo Remote Agent manually. You may also be interested in the Legacy remote agent installation guide if you have implemented your own remote agent service wrapper.

Before you begin:

Step 1. Enable remote agent support

  1. Click the  icon and select Overview.
  2. Click Agents (under 'Build Resources')
  3. Click either Enable Remote Agent Support or Disable Remote Agent Support.

Read more about enabling and disabling remote agent support here.

On this page:

Important note

Icon

Bamboo remote agents are available only for Downloaded Bamboo - NOT for OnDemand Bamboo because of the OnDemand restrictions.

Step 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. Click the  icon and select Overview.
  3. Click Agents in the left panel (Under Build Resources). This will display the 'Agents' screen, showing lists of all local agents and all remote agents that currently exist on your Bamboo system.
  4. If not already enabled, click the Enable remote agent support link 
  5. Click Install Remote Agent. The 'Installing a remote agent' screen will display
  6. Click 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 2 below.

Step 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:

Where X.X represents your Bamboo version number.

(info) 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.

Icon

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

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

Please see Configuring capabilities for more on defining capabilities.

35 Comments

  1. I want to run a remote agent at startup of a machine, and I see a suggestion to consult OS docs for that. It would be more helpful to provide examples for Linux and Windows as JIRA and Confluence do.

  2. Mac OSX 10.4+ users:

    If you want to set up the Bamboo agent to automatically start up on a OSX system, create a file called com.atlassian.BambooAgent.plist in folder /Library/LaunchDaemons/ whose content is: (you need to edit the file to replace YOUR_BAMBOO_AGENT_HOME, YOUR_BAMBOO_SERVER, YOUR_LOG_FOLDER, USERNAME_TO_RUN_WITH with proper values for your installation)

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
            <key>Disabled</key>
            <false/>
            <key>Label</key>
            <string>com.atlassian.BambooAgent</string>
            <key>OnDemand</key>
            <false/>
            <key>ProgramArguments</key>
            <array>
                    <string>/usr/bin/java</string>
                    <string>-Xmx1024m</string>
                    <string>-Dbamboo.home=YOUR_BAMBOO_AGENT_HOME</string>
                    <string>-jar</string>
                    <string>/usr/local/BambooBuildAgent/bamboo-agent-2.1.5.jar</string>
                    <string>http://YOUR_BAMBOO_SERVER/agentServer/</string>
            </array>
            <key>RunAtLoad</key>
            <true/>
            <key>ServiceDescription</key>
            <string>Atlassian Bamboo build agent</string>
            <key>StandardErrorPath</key>
            <string>YOUR_LOG_FOLDER/bamboo-agent-launchd.err</string>
            <key>StandardOutPath</key>
            <string>YOUR_LOG_FOLDER/bamboo-agent-launchd.out</string>
            <key>UserName</key>
            <string>USERNAME_TO_RUN_WITH</string>
    </dict>
    </plist>
    

    Enjoy.

    1. Anonymous

      Hi,

      Is it possible to start the Bamboo server on OS X automatically a similar manner as you have described, I have done a brief search around atlassian but have not found anything so far.  

      Thanks!

    2. With Lion (MacOS X 10.7) I've found that the above plist didn't work with version 3.3.2. but it set me on the right track. The following works a treat however.

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <dict>
      <key>Disabled</key>
      <false/>
      <key>Label</key>
      <string>com.atlassian.BambooAgent</string>
      <key>OnDemand</key>
      <false/>
      <key>ProgramArguments</key>
      <array>
      <string></full/path/to/bamboo-home>/bin/bamboo-agent.sh</string>
      <string>console</string>
      </array>
      <key>RunAtLoad</key>
      <true/>
      <key>ServiceDescription</key>
      <string>Atlassian Bamboo build agent</string>
      <key>StandardErrorPath</key>
      <string></full/path/to/bamboo-home>/logs/bamboo-agent-launchd.err</string>
      <key>StandardOutPath</key>
      <string></full/path/to/bamboo-home>/logs/bamboo-agent-launchd.out</string>
      </dict>
      </plist>
      You may also want to add
      <key>UserName</key>
      <string>USERNAME_TO_RUN_WITH</string>
      Also have a read of http://en.wikipedia.org/wiki/Launchd

      This also works for the Bamboo server.

  3. Suggest you add to the documentation the ability for windows users to customize ...\conf\wrapper.conf file and that the ...\bin\InstallBambooAgent-NT.bat can be used after the customization. Running the remote agent jar will always replace the file, so this is the only way to customize it. For instance, you can run the remote agent jar command first so that the wrapper config gets created, remove the service, customize wrapper.conf, and then re-install the service with the wrapper command. For instance, this can customize the Windows service name.

  4. Hello all,

    I used this page to help me download, install, and launch the new remote agent successfully but after 10-20 minutes the agent becomes unresponsive and goes offline.

    Does anyone know why this would happen and how I can prevent this?

    We had the same remote agent set up on a different server and it never went offline...

    Although, the log does show that the old agent did get "marked as inactive". but a "new one came in place" so it never went offline... 

    marked as inactive. A new one came in place.

    Jun 21, 2010 10:12:26 AM Remote agent "servername.domainname" came back after a period of inactivity.

    Thanks for any help!

    1. Hello Matthew,

      My apologies for the delay in response. If this issue has not been addressed, then to get a speedier response, I would recommend either lodging a support ticket or posting a forum message via the links at the end of this page (below).

      Kind regards,
      Giles.

  5. Anonymous

    How this guide applies to JIRA Studio?

    I understand that when you use Bamboo server it is possible to push the button and download JAR file with the Bamboo agent installer. But how it can be done if I have Bamboo server integrated with JIRA Studio?

    Thanks.

    1. Hello there,

      Please be aware that we do not support the integration of Bamboo remote agents with JIRA Studio.

      Instead, if you need to expand the number of agents available to Bamboo in your JIRA Studio site, we recommend that you achieve this by expanding the number of Elastic Instances as indicated in Getting Started with Bamboo in JIRA Studio guide.

      Best regards,
      Giles.

  6. Anonymous

    Hello, I 'm trying to run the remote agent as a service on a windows XP sp2 32 bits but still fails.

    I installed it with

    java -jar atlassian-bamboo-agent-installer-2.2.1.jar http://10.30.230.28:8085/agentServer/ installntservice

    then I tried to run it with both the service.msc window and the command net start "Bamboo Remote Agent".

    Both fails with

    The Bamboo Remote Agent service is starting.....
    The Bamboo Remote Agent service could not be started.
    A system error has occurred.
    System error 1067 has occurred.
    The process terminated unexpectedly.

    I also tried java -jar atlassian-bamboo-agent-installer-2.2.1.jar http://10.30.230.28:8085/agentServer/ start but then I got

    STATUS | wrapper  | 2010/09/15 17:43:42 | Starting the Bamboo Remote Agent service...
    INFO   | wrapper  | 2010/09/15 17:43:47 | Waiting to start...
    ...
    INFO   | wrapper  | 2010/09/15 17:45:04 | Waiting to start...
    ERROR  | wrapper  | 2010/09/15 17:45:09 | The Bamboo Remote Agent service was launched, but failed to start.
    Wrapper terminated with non zero exit code: 1
    Destroying underlying agent process...

    1. Anonymous

      I've just came across the same problem...Is anybody know how to solve it?

      Windows XP is my non-bamboo-server PC.

      1. Anonymous

        You should change the startup profile for the service. By default it runs from the SYSTEM and can not create necessary directories. Change the service startup profile to any existing admin account on the machine.

        1. I have installed Bamboo agent on windows 2008 server, and its going offline every time even if we run the services through the administrator. 

          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at org.tanukisoftware.wrapper.WrapperSimpleApp.run(WrapperSimpleApp.java:240)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at java.lang.Thread.run(Thread.java:744)
          INFO   | jvm 7    | 2014/01/21 19:07:44 | Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:385)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:292)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.validator.Validator.validate(Validator.java:260)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.ssl.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:326)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.ssl.X509TrustManagerImpl.checkTrusted(X509TrustManagerImpl.java:231)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:126)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1323)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     ... 28 more
          INFO   | jvm 7    | 2014/01/21 19:07:44 | Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:196)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:268)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:380)
          INFO   | jvm 7    | 2014/01/21 19:07:44 |     ... 34 more
          ERROR  | wrapper  | 2014/01/21 19:07:44 | JVM exited while starting the application.
          FATAL  | wrapper  | 2014/01/21 19:07:44 | There were 5 failed launches in a row, each lasting less than 3 seconds.  Giving up.
          FATAL  | wrapper  | 2014/01/21 19:07:44 |   There may be a configuration problem: please check the logs.
          STATUS | wrapper  | 2014/01/21 19:07:44 | <-- Wrapper Stopped

  7. Anonymous

    Is a Bamboo remote agent what I need to run a Bamboo build on a PC other than the Bamboo server PC?

    1. Anonymous

  8. Hey,

    Why don't you provide an /etc/init.d bamboo remote agent script?  Would be a nice thing to do don't you think?

    In fact even better, provide apt and rpm packages.

    That would be the right thing to do.

    1. Anonymous

      Seconded.  

        1. Anonymous

          Couldn't agree more

  9. Anonymous

    Could not get it started - it fails due to java.lang.NumberFormatException

     

    INFO   | jvm 1    | 2012/06/22 01:35:29 | ---- Debugging information ----

    INFO   | jvm 1    | 2012/06/22 01:35:29 | message             : For input string: "2012-06-22 08:29:48.186 UTC"

    INFO   | jvm 1    | 2012/06/22 01:35:29 | cause-exception     : java.lang.NumberFormatException

    INFO   | jvm 1    | 2012/06/22 01:35:29 | cause-message       : For input string: "2012-06-22 08:29:48.186 UTC"

    INFO   | jvm 1    | 2012/06/22 01:35:29 | class               : java.util.Date

    INFO   | jvm 1    | 2012/06/22 01:35:29 | required-type       : java.util.Date

    INFO   | jvm 1    | 2012/06/22 01:35:29 | converter-type      : com.thoughtworks.xstream.converters.SingleValueConverterWrapper

    INFO   | jvm 1    | 2012/06/22 01:35:29 | wrapped-converter   : com.atlassian.bamboo.persister.xstream.SecondsDateConverter

    INFO   | jvm 1    | 2012/06/22 01:35:29 | path                : /result/value/creationDate

    INFO   | jvm 1    | 2012/06/22 01:35:29 | line number         : 4

    INFO   | jvm 1    | 2012/06/22 01:35:29 | class[1]            : com.atlassian.bamboo.v2.build.agent.RemoteAgentDefinitionImpl

    INFO   | jvm 1    | 2012/06/22 01:35:29 | converter-type[1]   : com.thoughtworks.xstream.converters.reflection.ReflectionConverter

    INFO   | jvm 1    | 2012/06/22 01:35:29 | class[2]            : org.springframework.remoting.support.RemoteInvocationResult

    INFO   | jvm 1    | 2012/06/22 01:35:29 | version             : null

  10. Anonymous

    Is there any way to preconfigure build-dir? (Windows)

  11. If I set custom JVM sizings in the wrapper.conf, does this apply to just the agent process itself, or to the builds that will run on it?

  12. To auto-start under Ubuntu, do the following:

    1. Install Remote Agent as usual (the following assumes you installed under user "bamboo").
    2. Once the agent is registered, stop the process (CTRL+C).
    3. "sudo nano /etc/init/bamboo-agent.conf"
    4. Paste the following contents into the file:

    That's it. The remote agent will now start up on boot.

     

    These instructions are based on: http://ubuntuforums.org/showthread.php?t=1689525

  13. Anonymous

    I'm currently trying to evaluate the tool but i'm stuck with this error. The remote client can't start.  

     

    [WrapperSimpleAppMain] [AgentContext] Bootstrap Type: 'REMOTE'
    INFO | jvm 1 | 2012/10/19 14:43:16 | 2012-10-19 14:43:16,612 INFO [Thread-1] [RemoteAgent] com.atlassian.bamboo.v2.build.agent.remote.RemoteAgent starting.
    INFO | jvm 1 | 2012/10/19 14:43:16 | 2012-10-19 14:43:16,722 INFO [Thread-1] [RemoteAgentHomeLocatorForBootstrap] Agent home located at 'C:\Documents and Settings\svnbuild\bamboo-agent-home'
    INFO | jvm 1 | 2012/10/19 14:43:16 | 2012-10-19 14:43:16,737 INFO [Thread-1] [RemoteAgent] Starting Bamboo Remote Agent...
    INFO | jvm 1 | 2012/10/19 14:43:16 | 2012-10-19 14:43:16,737 INFO [Thread-1] [RemoteAgent] Starting application context...
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,753 WARN [Thread-1] [PropertyPlaceholderConfigurer] Could not load properties from class path resource [bamboo-init.properties]: class path resource [bamboo-init.properties] cannot be opened because it does not exist
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,784 INFO [Thread-1] [RemoteAgentHomeLocatorForBootstrap] Agent home located at 'C:\Documents and Settings\svnbuild\bamboo-agent-home'
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,784 INFO [Thread-1] [RemoteAgentHomeDirectoryLayout] Plugin directory: C:\Documents and Settings\svnbuild\bamboo-agent-home\plugins
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,784 INFO [Thread-1] [RemoteAgentHomeDirectoryLayout] Plugin cache directory: C:\Documents and Settings\svnbuild\bamboo-agent-home\caches\plugins
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,816 WARN [Thread-1] [AgentConfiguration] Configuration file does not exist. Creating File: bamboo-agent.cfg.xml
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,831 INFO [Thread-1] [AgentUuidInitializer] Found agent UUID '1e9eca0a-6c06-4ba6-9009-691640ec2447' in temporary UUID file 'C:\Documents and Settings\svnbuild\bamboo-agent-home\uuid-temp.properties'
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,831 INFO [Thread-1] [AgentConfiguration] Setting UUID in main config file to '1e9eca0a-6c06-4ba6-9009-691640ec2447'
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,862 INFO [Thread-1] [BambooActiveMQConnectionFactory] Setting broker URL to 'failover:(tcp://atc-bamboo1:54663?wireFormat.maxInactivityDuration=300000)?maxReconnectAttempts=10&initialReconnectDelay=15000'
    INFO | jvm 1 | 2012/10/19 14:43:17 | 2012-10-19 14:43:17,956 INFO [Thread-1] [BambooActiveMQConnectionFactory] Setting broker URL to 'failover:(tcp://atc-bamboo1:54663?wireFormat.maxInactivityDuration=300000)?maxReconnectAttempts=10&initialReconnectDelay=15000'

  14. Anonymous

    Same problem for me as with the previous comment. I cannot get the remote client working on Mac.

  15. Anonymous

    Is there a way to automatically rename the bamboo agent at installation?

  16. Anonymous

    I need instruction on how to configure autostart of bamboo agent on Centos x64

    1. Anonymous

      You need to create an init script for this.

  17. Anonymous

    Hi,

    I used the method describe above to install the bamboo agent on Mac OSX and start it as daemon. But I would like to set up a custom PATH for the bamboo agent so some of the tools installed get precedence over the default Mac OSX ones. I am wondering where is the best place to insert the custom PATH variable. In the plist file for the launch daemon or in the conf xml file in bamboo home? Any help is appreciated.

    Thanks in advance

  18. Step 1. 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. On your Bamboo server, click Administration in the menu bar.

    There is no menu called Administration.  Presumably you mean Bamboo Admin.

    1. Click Agents in the left panel. This will display the 'Agents' screen, showing lists of all local agents and all remote agents that currently exist on your Bamboo system.

    There is no link called Agents. Presumably you mean Agent Matrix.

    1. Click Enable Remote Agent Support, if necessary, and then Install Remote Agent.

    There is nothing called Enable Remote Agent Support

    1. Click DOWNLOAD Remote Agent JAR and save the JAR file to the directory on the agent machine that you created in step 1.1.

    There is nothing to download

    1. Take note of the command under the heading 'Running a Remote Agent' for use in step 2 below.



    1. Mg12, I use Bamboo OnDemand and have the same problems. Did you manage to solve them?

      1. Remote agents are not supported on OnDemand. This feature request is tracked here: BAM-11870 - Support remote agents on Bamboo OnDemand Open . Please comment and vote.

         

  19. Anonymous

    Suppressing the self-signed certificate of the server

    You might want to change the URL in the example to https:// (wink)

  20. Anonymous

    how to add bamboo-agent start-up service in mac os. If bamboo-agent is reboot, then it will automatically start on boot time.