The first thing you need to do is install Cruise agent on the machine you want to add to the cloud.

Once the Cruise agent has been installed and pointed at your Cruise server, go to the Agents tab on the Cruise dashboard. You should see something like this:

Note that the hostname is as reported by the agent, and the IP address is as reported by the server.

To add the agent to the cloud, click "Approve". Note that even after you have clicked "Approve", the agent will not be approved until it next contacts the server -- so if your agent has stopped talking to the server, nothing will happen.

Once your agent has successfully been approved, it should turn green and be marked "idle". At this point your agent will automatically begin picking up jobs. Agents will automatically check out any code they need in order to start running jobs.

In its default state, Cruise server will assign scheduled jobs to the first available agent. Cruise doesn't have the ability to determine what operating system or other resources are present on a given agent. If you want particular jobs to run on particular agents, you'll need to specify resources .

You can specify one or more resources that a particular job needs in order to execute. In the same way, you can specify that an agent has one or more resources. Cruise will then match jobs to agents, such that a job will only run on agents which have at least the resources required for that job.

Resources are just plain text tags. There are no preset tags or conventions around tagging -- just use what makes sense to you. You might, for example, use operating systems as tags: "RHEL linux", "Windows XP". You could also use browsers, databases, or whatever else makes sense. We recommend you let your classification be driven by your jobs -- if you know that certain jobs will only work on certain machines, tag the jobs with the special resource or resources that job needs in order to work, and then classify the agents accordingly.

To specify the resources that a job needs, go to the Pipelines configuration section of the Administration tab and edit the job that you want to specify resources for:

Once you've specified the resources your jobs need, you'll want to describe the resources your agents have. You can do this very easily in the Agents tab. Just find the agent you want to describe, and click on the Specify resources link. You can then add resources. Clicking on the X next to an existing resource name will remove it from the agent:

Cruise will tell you if it loses touch with agents. If Cruise server doesn't hear from an agent for two minutes, the agent will turn red in the Agents tab, and Cruise will tell you the last time it heard from the agent. Cruise will also transparently re-assign the build to the next available agent that can run it, if the lost agent was building a job.

Cruise will also let you know if one of the agents it knows about has never contacted it since Cruise server was last started. In this case, the agent's state will be marked as "missing" and it will be gray.

If an agent is working on a job, it will turn orange, and display the name of the job it is working on. You can click on the job description to go to the job details page for that job:

If you want to remove an agent from Cruise's build cloud, go to the agents tab, locate the agent you want to remove, and click on the link marked "deny". Cruise will record in its configuration that this agent should be excluded from the build cloud. If you restart Cruise server, the agent will continue to be denied. Denied agents do not count towards Cruise's licensed agents.

To re-approve a denied agent, or to permanently remove it from Cruise's configuration, you currently need to edit Cruise's configuration file. Go to the Source XML section of the Administration tab. Edit the configuration file content, and scroll down to the <agents> section. You can then delete the agent and save the configuration file.

Following this procedure, if you restart the agent, Cruise server will see it as a new agent, and you can approve it again in the same way as described above.