Master-agent architecture in Jenkins - Commands & Configuration

Introduction

Jenkins uses a master-agent setup to split work between a main server and multiple worker machines. This helps run many tasks at once without slowing down the main server.

When you want to run multiple builds or tests in parallel to save time.

When your main Jenkins server should stay free to manage jobs and not run heavy tasks.

When you have different machines with special tools or environments for specific jobs.

When you want to add more workers easily to handle more jobs as your team grows.

When you want to isolate jobs so one failing task does not affect others.

Config File - agent-config.xml

agent-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<slave>
  <name>example-agent</name>
  <description>Agent for running builds</description>
  <remoteFS>/home/jenkins</remoteFS>
  <numExecutors>2</numExecutors>
  <mode>NORMAL</mode>
  <retentionStrategy class="hudson.slaves.RetentionStrategy$Always"/>
  <launcher class="hudson.slaves.JNLPLauncher">
    <workDirSettings>
      <disabled>false</disabled>
      <internalDir>remoting</internalDir>
      <failIfWorkDirIsMissing>false</failIfWorkDirIsMissing>
    </workDirSettings>
  </launcher>
  <label>linux</label>
  <nodeProperties/>
</slave>

This XML file configures a Jenkins agent (worker).

name: The agent's name.

remoteFS: The folder on the agent machine where Jenkins stores files.

numExecutors: How many jobs the agent can run at once.

launcher: How the agent connects to the master (here using JNLP).

label: A tag to select this agent for specific jobs.

Commands

This command starts the Jenkins agent on the worker machine. It connects to the Jenkins master using the JNLP protocol with a secret key for security.

Terminal

java -jar agent.jar -jnlpUrl http://jenkins.example.com/computer/example-agent/slave-agent.jnlp -secret 1234567890abcdef -workDir "/home/jenkins/agent"

Expected Output

[Jenkins agent] Started

Connecting to http://jenkins.example.com/computer/example-agent/slave-agent.jnlp

Connected

Waiting for tasks...

→

-jnlpUrl - URL to connect the agent to the Jenkins master

→

-secret - Security token to authenticate the agent

→

-workDir - Directory on the agent machine for Jenkins files

This command removes the agent named 'example-agent' from the Jenkins master. Useful to clean up agents no longer needed.

Terminal

curl -X POST http://jenkins.example.com/computer/example-agent/doDelete

Expected Output

No output (command runs silently)

Starts the Jenkins agent in the background so it keeps running even after closing the terminal.

Terminal

java -jar agent.jar -jnlpUrl http://jenkins.example.com/computer/example-agent/slave-agent.jnlp -secret 1234567890abcdef -workDir "/home/jenkins/agent" &

Expected Output

[Jenkins agent] Started

Connecting to http://jenkins.example.com/computer/example-agent/slave-agent.jnlp

Connected

Waiting for tasks...

→

& - Run the process in the background

Key Concept

If you remember nothing else from this pattern, remember: Jenkins master manages jobs and agents run the jobs, allowing parallel and isolated work.

Common Mistakes

Starting the agent without the correct secret key.

The agent will fail to connect because Jenkins master rejects unauthorized agents.

Use the exact secret key provided by Jenkins for that agent when starting it.

Running multiple agents on the same machine without adjusting numExecutors.

Agents may overload the machine or Jenkins may not schedule jobs properly.

Set numExecutors to match how many jobs the machine can handle simultaneously.

Not running the agent in the background on the worker machine.

Agent stops when the terminal closes, interrupting builds.

Use '&' or a service manager to keep the agent running continuously.

Summary

Configure agents with XML files specifying connection and capacity details.

Start agents on worker machines using the java -jar agent.jar command with proper flags.

Use agents to run jobs in parallel, keeping the Jenkins master free to manage tasks.