Controller & agent architecture

Why builds never run on the controller.

A healthy Jenkins has two kinds of machine. The controller is the brain: it serves the web UI, stores configuration and job history, schedules work, and orchestrates everything — but it should run no builds itself. Agents (historically "nodes" or "slaves") are the workers: they connect to the controller and actually execute the build steps. The controller decides; the agents do.

Why builds never run on the controller

This is the single most important architectural rule in Jenkins, and it is a security rule. The controller holds every credential, every job definition, and the keys to your whole delivery pipeline. A build is arbitrary code — a Jenkinsfile, a test, a dependency — and if that code runs on the controller, a malicious or compromised build can read every secret and take over the entire instance. Keep builds on agents so a poisoned build is contained to a disposable worker.

# lock the built-in node to zero executors so nothing can build on the controller
# Manage Jenkins → Nodes → Built-In Node → # of executors: 0
# then all work is forced onto agents (labelled, e.g. "linux", "docker")

Agents connect to the controller in one of two directions: the controller launches them (over SSH), or the agent dials in (inbound, via a JNLP/WebSocket connection) — useful when the agent is behind a firewall. Modern setups make agents ephemeral, spinning up a fresh container or cloud VM per build and destroying it after, so every build starts from a clean, uncontaminated workspace.