Agents are lightweight Java processes that connect to the Jenkins controller to execute build tasks, enabling distributed builds across multiple machines with different operating systems and environments
Agents in Jenkins are the worker machines responsible for executing build jobs. They run as small Java client processes that establish a connection to the Jenkins controller, receive instructions, and perform tasks like compiling code, running tests, or creating artifacts. The agent architecture allows Jenkins to distribute workloads across multiple machines, each potentially with different operating systems, toolchains, or hardware configurations, all managed from a single central controller.
Jenkins uses a controller-agent (formerly master-slave) architecture where the controller manages the system state, schedules jobs, and serves the web UI, while agents execute the actual build tasks. The controller delegates work to agents, which run the builds and report results back. This separation ensures that heavy build workloads don't impact the responsiveness of the Jenkins web interface and allows builds to run on specialized hardware or operating systems.
Lightweight: The agent client is small (around 170KB) and runs as a Java process, making it easy to deploy on any machine that supports Java.
Connection-based: Agents connect to the controller and maintain a persistent connection, waiting for work assignments rather than requiring inbound connections from the controller.
Self-registering: Once configured, agents announce their availability, capabilities, and labels to the controller, enabling dynamic task matching.
Platform-independent: Agents can run on any operating system, enabling cross-platform builds where compilation might happen on Linux, testing on Windows, and packaging on macOS.
Agents can connect to the controller using several methods depending on network topology and security requirements. The most common is launching agents via SSH, where the controller initiates the connection. For environments where agents are behind firewalls, the JNLP (Java Web Start) or WebSocket methods allow agents to initiate outbound connections to the controller. In containerized environments, agents can run as Docker containers or Kubernetes pods that spin up only when needed and terminate after job completion.
Agents can be tagged with labels that describe their capabilities, such as 'linux', 'docker', 'high-memory', or 'arm64'. When defining a job, you specify label requirements, and Jenkins automatically assigns the job to an agent that matches all required labels. This abstraction decouples build logic from specific machine names, making pipelines more portable and infrastructure more flexible.
Jenkins includes a built-in node that runs within the controller process itself. While technically capable of running builds, this is strongly discouraged for security, performance, and scalability reasons. Best practice is to configure the built-in node with 0 executors and route all build work to dedicated agents. This separation ensures the controller remains responsive for scheduling and user interface tasks regardless of build load.
Agents operate with the permissions of the user account they run under. For security, production deployments should enable SSL/TLS for controller-agent communication, use SSH keys rather than passwords, and consider using ephemeral agents in containerized environments to ensure clean, isolated builds. The controller also needs to verify that connected agents are authorized to perform the tasks assigned to them.