jenkinsci/docker-agents: the base and inbound agent images behind Jenkins builds

Two images, two different jobs

The repository ships two image families. The first, jenkins/agent, is described in the README as a base image for Docker that includes a JDK and the Jenkins agent executable, agent.jar. It does not connect to anything on its own. The second, jenkins/inbound-agent, is built on top of the first and is for Jenkins agents that use TCP or WebSockets to establish an inbound connection to the Jenkins controller. That distinction decides which image you pull. If you are writing your own Dockerfile and want the remoting jar plus a JDK preinstalled, start from jenkins/agent. If you want a container that dials back to a controller, start from jenkins/inbound-agent. The repository also carries a PowerShell entry point, jenkins-agent.ps1, and a jenkins-agent shell script, which is why the primary language is listed as PowerShell even though most of the build machinery is a Makefile.

What docker-bake.hcl actually defines

The build is driven by docker buildx bake against docker-bake.hcl, not by a single Dockerfile. The bake file declares groups and targets. Groups are named alpine, debian, rhel_ubi9, linux and default; linux aggregates alpine, debian and rhel_ubi9. Targets follow a naming pattern of agent or inbound-agent, then the flavor, then the JDK version, for example agent_alpine_jdk21 and inbound-agent_debian_jdk25. Each target points at a Dockerfile such as alpine/Dockerfile and carries build args and tags. In the README's example output, the alpine agent target uses ALPINE_TAG 3.24.1 and VERSION 3391.va_37fa_a_305d6d, and produces tags including docker.io/jenkins/agent:alpine and docker.io/jenkins/agent:latest-alpine. The JDK comes from the adoptium directory, which is present at the top level of the repository. The Makefile exports DOCKER_BUILDKIT=1 and DOCKER_CLI_EXPERIMENTAL=enabled with a comment saying those are for Docker 20.04 and earlier, and sets BUILDKIT_PROGRESS=plain so build output stays on stdout. It also derives OS and ARCH from uname, mapping Darwin to linux and MSYS, MINGW and CYGWIN to windows, and mapping x86_64 to amd64 and aarch64 or arm64 to arm64. That derivation is the reason a Mac can list Linux targets without extra flags.

Installing nothing: pulling the image and running a first build

There is no install step for the images themselves. They are published on Docker Hub at jenkins/agent and jenkins/inbound-agent, which is the homepage the repository points to. You pull a tag and run it. The repository's own README covers building the images from source rather than consuming them, so the commands below come from that build workflow and from the target naming it documents. To see which images your current OS and architecture would build, run the list target. The README shows this printing entries such as agent_alpine_jdk21 and inbound-agent_debian_jdk25 on Linux.

make list

To see every target, including Windows variants that your platform would not build, use list-all, which the README shows returning nanoserver and windowsservercore targets alongside the Linux ones.

make list-all

To build one specific image, the documented form is build- followed by agent type, flavor and JDK version. The README gives this exact example for an inbound agent on Debian with JDK 25.

make build-inbound-agent_debian_jdk25

To test a specific image, the same pattern applies with the test- prefix, and the README gives the matching example.

make test-inbound-agent_debian_jdk25

Before any of this runs, the Makefile's check-reqs target verifies that bash, git and docker are on the PATH and that the Docker BuildX plugin is present. If buildx is missing, the target prints an error and exits. The README also documents listing tags for publication by setting ON_TAG, optionally with BUILD_NUMBER, which is what you would use to inspect the tag set that a release would push.

ON_TAG=true BUILD_NUMBER=3 make tags

The Windows targets are a separate platform budget

The full target list is much wider than the Linux one. Running make list-all surfaces agent and inbound-agent targets for nanoserver-ltsc2022, nanoserver-ltsc2025, windowsservercore-ltsc2022 and windowsservercore-ltsc2025, each with JDK 21 and JDK 25 variants, in addition to the alpine, debian and rhel_ubi9 targets. The default make list output only shows what matches your current OS and architecture, so a Linux workstation will not display the Windows entries at all unless you override OS and ARCH. The README shows that override explicitly: OS=windows ARCH=amd64 make list returns the nanoserver and windowsservercore targets. This matters when you are deciding whether the repository can serve a mixed fleet. It can, but the Windows images are a distinct set of targets with their own base images, and the PowerShell files at the repository root (jenkins-agent.ps1, make.ps1) exist for that side. If your estate is Linux only, the Windows targets are noise in the output and nothing more.

Where this repository is the wrong tool

This is a build repository, not a runtime you install into an existing Jenkins. If you already run a controller and just need agent capacity, cloning and building these images is unnecessary work; pull the published image instead. The Makefile also assumes a Unix-like shell. It calls bash, git and docker through a check_cli macro and uses uname to infer OS and ARCH, and the Makefile itself notes that Darwin maps to linux, so building on macOS produces Linux targets rather than native ones. Anyone on a Windows host without a POSIX shell is steered to make.ps1 rather than the Makefile, and the README's build and test instructions are written for Linux. The README does not document rollback or how to revert a published tag, and it does not state a support window for older JDK lines; the target list simply shows jdk21 and jdk25. If you need an agent image with a specific toolchain baked in (a compiler, a browser, a language runtime), these images give you the JDK and the agent executable and leave the rest to your own Dockerfile. Treating jenkins/agent as a general purpose build image will disappoint.

How it compares to a hand-rolled agent Dockerfile

The obvious alternative is writing your own Dockerfile that downloads agent.jar from the controller and runs it. That approach gives you total control over the base OS, the JDK vendor and the installed packages, and it is the right answer when your build needs a toolchain these images do not carry. The difference in approach is maintenance. With a hand-rolled Dockerfile you own the JDK upgrade, the base image digest and the remoting version, and you find out about a mismatch when a build fails. With this repository you inherit a matrix that is already built and tested across alpine, debian and rhel_ubi9 on JDK 21 and JDK 25, with the version baked in as a build arg (the README's example shows VERSION 3391.va_37fa_a_305d6d). The trade is breadth for control: fewer decisions to make, less freedom about what is inside. A middle path is to use jenkins/agent as your FROM line and add your toolchain on top, which keeps the JDK and agent.jar handling in the upstream image while your Dockerfile only carries what is specific to your builds.

Maintenance, releases and the MIT licence

The last push to the default branch was on 2026-09-10, and the most recent release listed is 3391.va_37fa_a_305d6d-2 from 2026-09-09, with 3391.va_37fa_a_305d6d-1 on 2026-08-31 and 3386.v353e57a_1b_ea_0-3 the same day. Those version strings track the bundled remoting version, so upgrading the image is how you move the agent's remoting code, not a separate step. The repository is not archived. There is an updatecli directory at the top level, which is the usual place for automated dependency updates, so base image and JDK bumps appear to be driven by tooling rather than by hand. For consumers, the upgrade cost is a tag change plus whatever your controller's remoting compatibility requires. The licence is MIT, which is permissive and places few conditions on redistribution of the image contents; the base operating system images underneath (Alpine, Debian, Red Hat UBI) carry their own terms, and the README does not restate them, so check those separately if you redistribute. Nothing here is legal advice.

Editorial conclusion

Adopt these images if you run Jenkins and need agent containers that connect inbound to a controller over TCP or WebSockets, and pick the tag matching your JDK and base OS. Do not adopt the repository as a build system unless you actually need to produce your own variants, because the Makefile requires bash, git, docker and the BuildX plugin before anything runs. Verify first which of the two images you need: jenkins/agent is a base with the JDK and agent.jar, while jenkins/inbound-agent adds the inbound connection. Confirm the exact tag you pull exists for your architecture, since the target list differs between linux and windows.

Frequently asked questions

Official sources

1. jenkinsci/docker-agents on GitHub
2. License: MIT
3. Project website
4. README
5. Releases