How to run an agent from the cloud?

I am writing a plugin for some cloud provider and stuck with the following problem:
My TeamCity server starts an instance from the image with preinstalled agent on it. After an instance is running the server connects to an instance and edits the file (according to
When I start an agent manualy it appears as a separate entity in an agent pool, not under cloud profile. There is a difference between mine and the one local-cloud ( sample plugin generates. It has an extra and properties presented.

Am I missing something in the agent configuration?
What are the requirements for an agent to be attached to the cloud instance in TeamCity?

Thank you,

Anton Karavaev

Comment actions Permalink


Sorry, for long delay. We had vocations and holidays during x-mas/NY time

The properties you've mentioned are provided to the cloud plugin via jetbrains.buildServer.clouds.CloudInstanceUserData interface.
It's expected by the system that you pass all parameter from jetbrains.buildServer.clouds.CloudInstanceUserData#getCustomAgentConfigurationParameters to

Those (and maybe other parameters) are used by the server to associate an agent with your cloud agent provider.

The thing is that you my add any number of additional parameters to that were used in #findInstanceByAgent method.

You may take alook at

Comment actions Permalink


I have added these two custom properties, and now my file after my plugin updates it, has the following properties:









system.prop.ImageId and system.prop.InstanceId are used in jetbrains.buildServer.clouds.CloudClient#findInstanceByAgent

But it looks like TeamCity does not execute this method from my plugin`s instance.

Furthermore, local-cloud sample plugin also does not automaticaly start an agent. After local agent configuration has the following content:


Only after I manually start an agent it appears in the pool under cloud profile.

When local agent starts it registers itself on the server with the following output in <TC_HOME>/temp/tc_buildAgent_4202729115835418780/logs/output.log

Registering on server http://localhost:8111, AgentDetails{Name='img-local-5', AgentId=null, BuildId=null, AgentOwnAddress='null', AlternativeAddresses=[], Port=9090, Version='29581', PluginsVersion='NA', AvailableRunners=[Ant, gradle-runner, Ipr, JPS, rake-runner, simpleRunner, Xcode], AvailableVcs=[perforce, mercurial, jetbrains.git, svn, cvs], AuthorizationToken='94e00d0b708d1b012c27552d79c2dfa3'}

My build agent has the following parameters. I thinnk they may be wrong, but I do not know how to properly set them.

Registering on server http://my-tc-server:8111, AgentDetails{Name='', AgentId=null, BuildId=null, AgentOwnAddress='null', AlternativeAddresses=[], Port=9090, Version='29581', PluginsVersion='29581-md5-3c810dae81b07ac7cfef0b0968245b7c', AvailableRunners=[Ant, Duplicator, gradle-runner, Inspection, Ipr, JPS, Maven2, rake-runner, simpleRunner], AvailableVcs=[perforce, mercurial, jetbrains.git, svn, cvs], AuthorizationToken=''}

As an alternative solution I think I can use "Install Agent on remote host (agent push)" plugin from TeamCity distibution: <WEB-INF>/.unpacked/agent.push
In my opinion this solution is better than launching an instance with preinstalled agent, and I see that Amazon EC2 plugin uses this plugin to automaticaly install build agent on new instance.
But I do not see any documentation or API of how to use it. Can you provide any information about this plugin?

P.S. My TeamCity version is 8.1 EAP (build 29581)

Comment actions Permalink

There is no necessitiy to have an image with pre-installed build agent. A cloud integration may solve this via cloud specific APIs. I'd say this is the best relayable way.

Unfortunately, we have no specific doc for agent-push plugin. The idea behind it is to start build agent once cloud integration returns a running instance. Agent-Push plugin is only available for Amazon EC2 instances. So for any other instances it would not attempt pushing an agent (please file an issue to the tracker for that)

Your plugin fail to work, so you may chage the following things:
- you patch the same as used from cloud-started build agent (try enable debugging for that)
- your cloud plugin implementation synchronously adds started instance to model once #startInstance returns. Instance ID is not changed.
- you may debug server-side logs to see weather started cloud agent attempts to connect and what properties were submitted (you may debug requests to /RPC2 path)
- your agent connects to the right server (you specified right server own URL under Administaration | Server settings, you pass)
- you update server.url property in
- you set name property to empty string in
- you do not have revese proxy between server and agent (agent - server is two-way HTTP connection. So sever should be able to resolve agent's IPv4 address to connect back. Reverse proxy may spoil it. See for more details)
- you see the running cloud instance of an agent in Agent | Clounds tab on the server UI

TeamCity may not populate clouds if you have an empty build queue. So you may add something to the queue to make it run.

Comment actions Permalink

Thanks Eugene for such complete answer. My problem was that my properties for image and instance id had "system." prefix :)


Please sign in to leave a comment.