Before Docker enters the picture, it helps to understand what an “agent” even is in Jenkins.

The controller-and-agent model

Jenkins separates two roles. The controller is the central brain — it stores configuration, schedules builds, and shows the web dashboard. The actual work of a build — compiling code, running tests, packaging an application — happens on an agent, which is simply a machine (or, as this guide covers, a container) that Jenkins connects to and hands instructions. A single Jenkins installation might have dozens of agents, each possibly running a different operating system or toolset, so that different projects can run on the environment they actually need.

The problem with permanent, hand-built agents

Traditionally, an agent is a long-lived virtual machine or physical server that an administrator sets up once, installing exactly the compilers, SDKs, and command-line tools a team’s builds need. Over months, these machines tend to accumulate small differences from each other and from what a fresh install would look like — an extra library here, a slightly different tool version there — a phenomenon commonly called configuration drift. A build that mysteriously “works on this agent but not that one” is one of the most common and frustrating problems in traditional CI setups.

Docker agents exist to remove that drift entirely, by defining the exact environment a build needs as code, right alongside the pipeline itself — which is exactly what the next chapter unpacks.

A Docker agent tells Jenkins to run a build’s steps inside a freshly started container, instead of on a pre-existing machine.

Declaring it in a pipeline

In a declarative Jenkinsfile, a build can specify an agent block that names a Docker image rather than a static label. When Jenkins reaches that stage, instead of looking for an already-running machine with a matching label, it asks the Docker daemon to start a brand-new container from the named image, and then runs every step in that stage’s block inside that container’s filesystem.

What “the image” really provides

The Docker image referenced determines everything about the environment the build steps see: which operating system distribution is present, which language runtimes and compilers are installed, and which command-line tools are available on the path. Choosing a Docker agent is really choosing to describe a build’s environment declaratively and reproducibly, the same image tag producing the same environment whether it runs today, next month, or on a completely different physical machine.

This declarative simplicity hides a fair amount of coordination behind the scenes between Jenkins, the underlying machine running Docker, and the container it starts — which is the subject of the architecture and internal-working chapters that follow.

Several distinct pieces cooperate to make a Docker agent work — understanding each one clarifies what is actually happening.

Where the host machine fits in

Every Docker agent still depends on a real, underlying machine — sometimes called the “Docker host” — that has the Docker engine installed and running. This host is typically configured once as a regular Jenkins agent equipped with Docker, and every Docker-based pipeline stage that runs there simply asks that same host’s Docker daemon to spin up a fresh container per build. The host machine itself is reused across many builds; only the containers it spawns are disposable.

flowchart TD
    A[Jenkins Controller] -->|assigns stage| B[Docker Host Agent]
    B --> C[Docker Daemon on Host]
    C -->|docker run| D[Ephemeral Build Container]
    D -->|mounts| E[Shared Workspace Directory]
    D -->|executes| F[Pipeline Steps for This Stage]
    F -->|stage completes| G[Container Stopped and Removed]
        

Why the workspace mount matters

A build container needs access to the project’s checked-out source code and needs to leave behind any artifacts it produces, such as compiled binaries or test reports, so Jenkins can collect them after the container disappears. Jenkins accomplishes this by mounting the workspace directory from the host machine directly into the running container, so files written inside the container during the build actually land on the host’s disk and survive after the container itself is gone.

With the pieces named, the next chapter walks through exactly how Jenkins coordinates them, from the moment a stage begins to the moment the container disappears.

A closer look at the sequence of operations behind that one line of pipeline syntax.

Step 1 — Stage begins, image is identified

When Jenkins reaches a stage declaring a Docker agent, it first resolves which underlying host machine will actually run the container — typically a machine already registered with Jenkins that has the Docker Pipeline plugin’s requirements satisfied — and reads the image name and any additional run arguments specified.

Step 2 — Pulling the image, if needed

The Docker daemon on the chosen host checks whether the requested image, at the specified tag, already exists locally. If it does not, the daemon pulls it from the configured registry — a public registry, or a private organizational one — before anything else can proceed. This pull can be the slowest part of the whole process on a host that hasn’t recently used that particular image.

Step 3 — Starting the container

Once the image is available locally, the daemon starts a new container from it. Jenkins passes along any options the pipeline specified, such as additional volumes to mount or environment variables to set, and — critically — mounts the current build’s workspace directory into the new container at the same path it would normally occupy on a traditional agent, so existing pipeline steps continue to work unmodified.

Step 4 — Running the stage’s steps inside the container

With the container running, Jenkins executes every step defined in that stage as a command inside the container, rather than on the host machine directly. From the perspective of the pipeline script, nothing looks different — a checkout, a shell command, a test runner — but each of these commands now actually executes using the tools and filesystem installed in the container’s image, not whatever happens to be installed on the host.

Step 5 — Tearing the container down

Once the stage’s steps finish, whether successfully or with a failure, Jenkins stops and removes the container. Because the workspace directory was mounted from the host rather than copied into the container, any files the build produced remain safely on the host’s disk, ready for later stages or for Jenkins to archive as build artifacts.

sequenceDiagram
    participant JF as Jenkinsfile Stage
    participant PE as Pipeline Engine
    participant DH as Docker Host
    participant DD as Docker Daemon
    participant C as Container
    JF->>PE: agent { docker { image '...' } }
    PE->>DH: Assign stage to Docker-enabled host
    DH->>DD: Check for image locally
    DD-->>DH: Pull image if missing
    DD->>C: Start container, mount workspace
    PE->>C: Execute stage steps
    C-->>PE: Step output and exit codes
    PE->>DD: Stop and remove container
        

With the mechanics understood, it’s worth zooming out to see exactly where this container’s short life fits inside the larger lifecycle of a full pipeline run, which the next chapter covers.

A single build might create and destroy several containers in sequence, one per stage, without the pipeline author ever managing that directly.

Why the workspace, not the container, is the constant thread

Because each stage’s container is created and destroyed independently, it is the mounted workspace directory on the host — not any single container — that carries state from one stage to the next within the same build. This is why a file written by an earlier stage’s container is visible to a later stage’s completely different container: both containers had the same host directory mounted in, even though neither container itself persisted.

Understanding this separation between disposable containers and a persistent workspace sets up the next chapter’s comparison of the different ways a Docker agent can actually be declared in a pipeline.

Jenkins offers more than one syntax for using Docker as an agent, each suited to a slightly different need.

Whichever syntax is used, the underlying host still needs a working Docker installation reachable by Jenkins — a requirement with real implications for how these hosts should be secured, which the security chapter later in this guide addresses directly.

Docker is one of several ways Jenkins can provision an agent — seeing it alongside the alternatives clarifies when it’s the right choice.

Docker agents sit in a comfortable middle ground: they offer nearly the same clean-slate isolation as a full virtual machine or Kubernetes pod, but start dramatically faster, because they share the host machine’s kernel instead of booting an entire operating system. This is precisely why Docker agents became popular for everyday CI workloads, while heavier VM-per-build approaches are typically reserved for cases needing the very strongest isolation.

These trade-offs between speed, isolation, and setup effort are exactly what the next chapter’s advantages and disadvantages discussion builds on directly.

Docker agents solve real, painful problems, but they introduce their own costs and constraints.

The most serious of these trade-offs is security, since a Docker agent’s power comes directly from talking to a Docker daemon — which is exactly what deserves careful attention next.

Talking to a Docker daemon is a powerful capability, and powerful capabilities need to be handled carefully.

Why Docker access is sensitive

Whoever can instruct a Docker daemon to start a container with the right options can typically gain access to the entire host machine that daemon runs on — for example, by mounting the host’s root filesystem into a container and modifying it directly. This means that any pipeline capable of running arbitrary Docker commands on a given host effectively has significant control over that host, which matters enormously when untrusted or third-party pipeline code might run on shared build infrastructure.

Trusting the images themselves

Beyond daemon access, the image a Docker agent pulls is itself a piece of trust: an image sourced from an unverified public registry could contain tampered tools or malicious startup behavior. Pulling images from a controlled, internally-mirrored registry, and pinning to specific verified tags rather than a constantly-changing “latest” tag, closes off a meaningful category of supply-chain risk.

Once these access boundaries are in place, the next concern is simply knowing what actually happened during a build — which containers ran, from which images, and how long they took — the focus of the monitoring chapter that follows.

Because containers vanish the moment a stage finishes, knowing what to look at while they’re still running — and right after — matters.

Watching for host-level drift too

Even though the containers themselves are disposable, the host running the Docker daemon is not, and it still needs its own monitoring — disk space consumed by old, unused images, the version of the Docker engine installed, and available capacity for running multiple containers at once. Periodically clearing out unused images and containers keeps a busy build host from silently running out of disk space over time.

Good visibility into both the containers and the host beneath them makes it much easier to notice when a pipeline is using Docker agents in a way its designers never intended — which leads naturally into the design patterns worth recognizing next.

Some ways of using Docker agents age gracefully; others quietly accumulate problems.

These same principles — small, purposeful, well-owned images — translate directly into the concrete best-practices checklist covered next.

A short, practical checklist for anyone configuring or using Docker agents in Jenkins.

With these practices in hand, it’s worth seeing how organizations actually put Docker agents to work at scale, which the next chapter explores.

Docker agents show up in a wide range of real CI/CD setups, well beyond simple demonstration pipelines.

Before closing out, it’s worth addressing the handful of questions that come up most often once engineers start relying on Docker agents day to day.

Only the specific hosts that pipelines will actually assign Docker-based stages to need Docker installed and configured; other agents in the same Jenkins environment can remain plain, non-Docker machines.

By default a container can reach the network the same way the host can, unless the pipeline or host configuration explicitly restricts it — Docker’s isolation is primarily about filesystem and process separation, not network access.

The Docker daemon’s pull attempt fails, and the stage fails immediately before any pipeline step runs, similar to how a missing Shared Library repository fails a build before any stage output appears.

No. A Docker agent starts a single container directly on a host’s Docker daemon, while a Kubernetes agent schedules a pod onto a cluster, which itself typically runs containers under the hood — the concepts are related but operate at different layers.

Only files written into the mounted workspace directory persist, because that directory actually lives on the host’s disk; anything written elsewhere inside the container’s own filesystem disappears along with the container.

The first build has to pull the image from the registry, which can take real time depending on image size and network speed; later builds reuse the same locally cached image and skip that step entirely, unless the image is updated in the meantime.

A Docker agent turns the once-informal question of “what’s installed on the build machine?” into an explicit, versioned, reviewable line in a Jenkinsfile. Underneath that simplicity sits real coordination — a host’s Docker daemon pulling an image, starting a container, mounting a shared workspace, running the stage’s steps, and tearing everything down again — repeated fresh for every single build. Used thoughtfully, with lean images, pinned versions, and careful control over who can actually reach the Docker daemon itself, Docker agents deliver consistent, drift-free build environments at a fraction of the setup cost of a fully provisioned virtual machine per build.