Jenkins Architecture

Before you install a single thing, you need to understand how Jenkins is built — because the architecture decides everything: how it scales, where it breaks, and why distributed builds exist in the first place.

Most beginners think of Jenkins as one program running on one server. That's true when you first install it. But the reason Jenkins has powered CI/CD at companies with hundreds of developers is that it was designed from the start to be split across multiple machines. Understanding that design — even before you touch a terminal — will save you a lot of confusion later.

The Airport Analogy

Think of a major airport. There's an air traffic control tower — it doesn't fly any planes. It tracks every flight, issues instructions, decides who lands and who waits, and makes sure nothing collides. The actual flying is done by the planes themselves, each with its own crew, fuel, and cargo.

Jenkins works exactly the same way. The Jenkins Master is the control tower — it receives instructions, schedules work, and tracks results. The Jenkins Agents are the planes — they do the actual work of running tests, compiling code, and deploying applications. The master never runs a build itself. It just directs traffic.

The Three Core Components

Every Jenkins installation — from a single laptop to a 50-node enterprise cluster — is made of the same three building blocks:

1. The Master (also called the Controller). This is the brain. It runs the Jenkins web interface you see in the browser, stores all configuration, manages the job queue, and decides which agent runs which job. It does not run build commands itself — best practice is to keep it lean and let agents do the heavy lifting.

2. Agents (also called Nodes or Workers). These are the machines that actually run your build steps — compiling code, running tests, building Docker images. An agent can be a physical server, a virtual machine, a Docker container, or a Kubernetes pod. You can have one or many. Each agent connects back to the master and says "I'm ready for work."

3. The Workspace. Every time an agent runs a job, Jenkins creates a workspace — a dedicated folder on that agent's disk where the code is checked out and all build files are created. When the build finishes, the workspace stays there (until cleaned up) so you can inspect what happened.

How It All Fits Together

Here's the architecture as a diagram. This is what's happening under the hood every time a build runs:

What Lives Where

It helps to know exactly what files and data Jenkins stores, and where. When something breaks, this is the map you use to find the problem:

How Jenkins Communicates With Agents

The master and agents need to talk to each other to coordinate work. Jenkins uses two main methods to make that connection:

SSH (most common). The master connects to the agent over SSH — the same secure protocol you'd use to log into a remote server. The master pushes a small Java program called the agent.jar to the agent machine, and that program handles all communication back.

JNLP / WebSocket (inbound). The agent reaches out to the master instead. This is useful when the agent is behind a firewall or in a cloud environment where the master can't directly SSH in. The agent starts up, connects to the master's URL, and waits for work.

The Build Flow, Step by Step

Here's exactly what happens the moment a build is triggered — from the first event to the final result being logged:

Now let's see this architecture in action. The first thing any engineer does when checking a Jenkins server is look at what nodes (agents) are connected and whether they're online. Here's how you do that from the command line.

The scenario:

You've just joined a platform team at a mid-sized SaaS company. It's your first week. Your lead tells you Jenkins has three agents configured but one of them has been throwing errors since yesterday. You need to check which agents are online, which are offline, and report back. This command gives you that picture in seconds.

Tools used in this command:

• java — Java is the programming language Jenkins itself is built on. You need Java installed to run Jenkins and to use the Jenkins CLI tool.
• jenkins-cli.jar — A small program provided by Jenkins that lets you control Jenkins from the terminal instead of clicking through the browser. You download it once from your Jenkins server.
• get-node — A Jenkins CLI command that fetches details about a specific agent (node) registered with the master.

# List all nodes (agents) registered with this Jenkins master
# 'get-node' with no node name listed returns info on all nodes
java -jar jenkins-cli.jar \
  -s http://jenkins-master-01:8080 \
  -auth admin:your-api-token \
  get-node

<slave>
  <name>agent-linux-01</name>
  <description>Primary Linux build agent</description>
  <numExecutors>4</numExecutors>
  <mode>NORMAL</mode>
  <retentionStrategy class="hudson.slaves.RetentionStrategy$Always"/>
  <launcher class="hudson.plugins.sshslaves.SSHLauncher">
    <host>10.0.1.45</host>
    <port>22</port>
  </launcher>
  <label>linux docker</label>
  <offline>false</offline>
</slave>

Practice Questions

Quiz