Types of Agents

Let’s review common Jenkins agent types and how to declare them in a Jenkinsfile. Agents extend the Jenkins controller by running executors on remote nodes and provide the execution environment for pipeline steps. An agent defines how a node connects to the controller — including the communication protocol and authentication method (for example, JNLP or SSH) — and the node where build tools and dependencies must be installed.

In addition to long-lived (static) agents, Jenkins supports container- and cloud-based agents that spawn ephemeral environments. Docker-based agents run each job in a fresh container built from a specified image, which is ideal when jobs require precise software versions or complex dependencies. This isolation ensures reproducible builds and prevents dependency conflicts between projects.

Agents are simply worker machines — physical, virtual, or containerized — that connect to the Jenkins controller and execute pipeline steps. Choosing the right agent type helps you balance cost, performance, and reproducibility for your CI/CD workloads.

Common agent types and when to use them:

Agent Type	When to use	Notes / Example
Permanent (dedicated) agents	When you need stable, long-lived machines with preinstalled tools (for example, corporate build servers with licensed software)	Use when consistency is more important than elasticity; can be resource-intensive if idle
Docker agents	When builds need specific tool versions or isolated environments (for example, Node.js or Python builds)	Each job runs in a fresh container based on a Docker image; ideal for reproducible builds
Cloud-based agents (including Kubernetes)	For on-demand scaling and pay-as-you-go CI/CD (for example, AWS EC2, Azure, or K8s pods)	Jenkins provisions ephemeral VMs or pods and terminates them after the job completes
Label-based agents	When you want flexible assignment based on capabilities (for example, `java`, `windows`, `nodejs`)	Pipelines request a label and Jenkins matches the job to an available agent with that label

Below are Declarative Pipeline examples showing common agent declarations inside a Jenkinsfile. Example 1 — Run the pipeline on any available agent:

pipeline {
    agent any   // Use any available agent
    stages {
        stage('Build') {
            steps {
                sh 'echo "Running on $NODE_NAME"'
            }
        }
    }
}

Example 2 — Run the pipeline on an agent with a specific label:

pipeline {
    agent {
        label 'my-agent'   // Run on an agent labeled "my-agent"
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Running on $NODE_NAME"'
            }
        }
    }
}

Example 3 — Use a Docker image as the agent:

pipeline {
    agent {
        docker {
            image 'node:latest'                   // Use a Docker image with Node.js
            args  '-v $HOME/.npm:/root/.npm'     // Optional: mount npm cache
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'node --version'
                sh 'npm --version'
            }
        }
    }
}

Example 4 — Default (root-level) agent with a stage-level override:

pipeline {
    agent {
        label 'MyAgent'   // Default agent used by stages unless overridden
    }
    stages {
        stage('Build') {
            agent { label 'nodejs-agent' }   // This stage uses a different agent
            steps {
                sh 'echo "Running build on $NODE_NAME"'
                sh 'node --version'
            }
        }
        stage('Test') {
            steps {
                sh 'echo "Running tests on $NODE_NAME"'   // Uses default MyAgent
            }
        }
    }
}

Best practice: set a root-level agent to provide sensible defaults for most stages, and override at the stage level when a specific environment is required (for example, a nodejs Docker image or a windows agent). When using shell steps, reference the agent name with "$NODE_NAME" (or $NODE_NAME in POSIX shells) so the job output clearly indicates which node executed the step.See also: Jenkins Agents Documentation and Using Docker with Jenkins.

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring

Backup and Configuration Management

Introduction

Watch Video