How to Add Agent in Jenkins: Step-by-Step Guide

To add an agent in Jenkins, go to Manage Jenkins > Manage Nodes and Clouds > New Node, then enter a name and select Permanent Agent. Configure the agent details like remote root directory and launch method, then save to connect the agent.

Syntax

Adding an agent in Jenkins involves these key steps:

• Node Name: Unique name for the agent.
• Type: Usually Permanent Agent for long-term use.
• Remote Root Directory: Folder on the agent machine where Jenkins stores files.
• Launch Method: How Jenkins connects to the agent (e.g., via SSH or JNLP).
• Labels: Tags to group agents for job assignment.

text

Node Name: <agent-name>
Type: Permanent Agent
Remote Root Directory: /home/jenkins
Launch Method: Launch agent via SSH
Labels: linux, build

Example

This example shows how to add a Linux agent using SSH:

1. Go to Manage Jenkins > Manage Nodes and Clouds > New Node.
2. Enter linux-agent-1 as the node name and select Permanent Agent.
3. Set /home/jenkins as the remote root directory.
4. Choose Launch agent via SSH and enter the agent's hostname and credentials.
5. Save and wait for Jenkins to connect.

text

Node Name: linux-agent-1
Type: Permanent Agent
Remote Root Directory: /home/jenkins
Launch Method: Launch agent via SSH
Host: 192.168.1.100
Credentials: SSH key or username/password
Labels: linux, build

Output

Agent linux-agent-1 connected successfully and is online.

Common Pitfalls

Common mistakes when adding agents include:

• Using incorrect remote root directory paths causing connection failures.
• Not setting proper credentials for SSH or other launch methods.
• Firewall or network issues blocking Jenkins from reaching the agent.
• Forgetting to install Java on the agent machine, which Jenkins requires.

Always verify network access and credentials before adding the agent.

text

Wrong way:
Launch Method: Launch agent via SSH
Host: wrong-hostname
Credentials: none

Right way:
Launch Method: Launch agent via SSH
Host: correct-hostname
Credentials: valid SSH key or username/password

Quick Reference

Step	Description
Go to Manage Nodes	Navigate to Manage Jenkins > Manage Nodes and Clouds
Create New Node	Click New Node and enter a unique name
Select Node Type	Choose Permanent Agent for a persistent agent
Configure Details	Set remote root directory, labels, and launch method
Set Credentials	Provide SSH keys or username/password for connection
Save and Connect	Save the configuration and wait for agent to go online

Key Takeaways

Add agents via Manage Jenkins > Manage Nodes and Clouds > New Node.

Set a unique name, remote root directory, and launch method correctly.

Use valid credentials and ensure network access to the agent machine.

Install Java on the agent machine before connecting.

Labels help assign jobs to specific agents efficiently.