Prerequisites

All examples in this guide use the public image. If you've mirrored the repository for your own use (for example, to your Docker Hub namespace), update your commands to reference the mirrored image instead of the public one.

For example:

• Public image: dhi.io/jenkins-agent:<tag>
• Mirrored image: <your-namespace>/dhi-jenkins-agent:<tag>

For the examples, you must first use docker login dhi.io to authenticate to the registry to pull the images.

What's included in this jenkins-agent image

This Docker Hardened jenkins-agent image includes the Jenkins Agent component in a single, security-hardened package:

• Jenkins Remoting library (agent.jar): Connects Jenkins agents to Jenkins controllers, located at /usr/share/jenkins/agent.jar (Remoting version 3345)
• Backward compatibility symlink: slave.jar → agent.jar at /usr/share/jenkins/slave.jar
• Eclipse Temurin JRE 21: Java runtime at /usr/bin/java (openjdk 21.0.10, Temurin-21.0.10+7)
• Bash shell: Included in the runtime image (required for running build jobs)
• Pre-configured work directory: /home/jenkins/agent
• TLS support: Standard TLS certificates included for secure communication

Start a jenkins-agent container

The jenkins-agent image is designed to connect to a Jenkins controller. The default CMD runs /usr/bin/java -jar /usr/share/jenkins/agent.jar automatically, so you can start the container without specifying a command.

docker run -i --rm --name jenkins-agent --init \
  dhi.io/jenkins-agent:<tag>

This command:

• Runs the agent in interactive mode (-i) — required for the remoting protocol
• Removes the container when it exits (--rm)
• Uses --init for proper signal handling
• Executes the default CMD to connect to a Jenkins controller

Expected behavior: Without a Jenkins controller connected, the agent outputs the remoting capacity handshake string and waits for input on stdin:

<===[JENKINS REMOTING CAPACITY]===>rO0ABXNyABpodWRzb24...

This is expected — the agent JAR is working correctly but waiting for a controller connection. This is not an error.

With work directory

Starting from Remoting 3.8, agents support work directories which provide logging by default and change JAR caching behavior:

docker run -i --rm --name jenkins-agent --init \
  -v agent-workdir:/home/jenkins/agent \
  dhi.io/jenkins-agent:<tag> \
  /usr/bin/java -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent

Expected output:

INFO: Using /home/jenkins/agent/remoting as a remoting work directory
INFO: Both error and output logs will be printed to /home/jenkins/agent/remoting
<===[JENKINS REMOTING CAPACITY]===>rO0ABXNyABpodWRzb24...

Environment variables

Example with custom environment variables:

docker run -i --rm --name jenkins-agent --init \
  -e TZ=America/New_York \
  -e AGENT_WORKDIR=/home/jenkins/agent \
  dhi.io/jenkins-agent:<tag> \
  /usr/bin/java -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent

Common jenkins-agent use cases

Basic agent connection

Connect an agent to a Jenkins controller using the URL, secret, and agent name provided by the controller:

docker run -i --rm --name jenkins-agent --init \
  dhi.io/jenkins-agent:<tag> \
  /usr/bin/java -jar /usr/share/jenkins/agent.jar \
  -url http://jenkins-controller:8080 \
  -workDir /home/jenkins/agent \
  -secret <secret> \
  -name <agent-name>

Agent with persistent work directory

Use a named volume to persist the agent work directory across container restarts:

docker run -i --rm --name jenkins-agent --init \
  -v jenkins-agent-work:/home/jenkins/agent \
  dhi.io/jenkins-agent:<tag> \
  /usr/bin/java -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent

Agent in Kubernetes

Deploy Jenkins agents in Kubernetes using a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: jenkins-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: jenkins-agent
  template:
    metadata:
      labels:
        app: jenkins-agent
    spec:
      containers:
      - name: jenkins-agent
        image: dhi.io/jenkins-agent:<tag>
        command: ["/usr/bin/java", "-jar", "/usr/share/jenkins/agent.jar"]
        args: ["-workDir", "/home/jenkins/agent"]
        volumeMounts:
        - name: agent-work
          mountPath: /home/jenkins/agent
        env:
        - name: AGENT_WORKDIR
          value: "/home/jenkins/agent"
      volumes:
      - name: agent-work
        emptyDir: {}

Agent with custom Java options

Configure JVM options for the agent:

docker run -i --rm --name jenkins-agent --init \
  dhi.io/jenkins-agent:<tag> \
  /usr/bin/java -Xmx512m -Xms256m \
  -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent

Official images vs Docker Hardened Images

Image variants

Docker Hardened Images come in different variants depending on their intended use. Image variants are identified by their tag.

• Runtime variants are designed to run the Jenkins agent in production. These images:

  • Run as the jenkins user
  • Include bash (required for build job execution)
  • Do not include a package manager
  • Contain only the minimal set of libraries needed to run the agent

• Build-time variants typically include dev in the tag name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

  • Run as the root user
  • Include a shell and package manager (apt-get 3.0.3)
  • Are used to build or compile applications

• FIPS variants include fips in the variant name and tag. They use cryptographic modules validated under FIPS 140, a U.S. government standard for secure cryptographic operations. Pulling FIPS variants requires a Docker subscription — the tags return 401 without one.

To view the image variants and get more information about them, select the Tags tab for this repository, and then select a tag.

Migrate to a Docker Hardened Image

To migrate your application to a Docker Hardened Image, update your Dockerfile or Kubernetes manifests. Common changes are listed in the following table of migration notes.

The following steps outline the general migration process.

1. Find hardened images for your app. Inspect the image tags for dhi.io/jenkins-agent and find the variant that meets your needs (runtime, dev, or FIPS).

2. Update the image reference in your Kubernetes manifests or Dockerfile.

   # In your Deployment manifest
   containers:
     - name: jenkins-agent
       image: dhi.io/jenkins-agent:<tag>
   

   Copy

3. Update the default CMD if needed. The DHI default CMD runs the agent jar directly. If your existing setup overrides the CMD, verify the java path is /usr/bin/java.

4. Verify the agent connects to the controller. After migration, confirm the agent appears as online in the Jenkins controller UI.

Troubleshoot migration

General debugging

Use Docker Debug⁠ to attach to a running container for debugging:

docker debug <container-name>

Permissions

The runtime image runs as the jenkins user. Ensure that mounted volumes and files are accessible to the jenkins user. You may need to set appropriate permissions on host directories before mounting them.

Deprecated positional arguments

Passing the secret and agent name as positional arguments is deprecated and produces a warning:

WARNING: Providing the secret and agent name as positional arguments is deprecated;
use "-secret" and "-name" instead.

Always use the -secret and -name flags explicitly:

/usr/bin/java -jar /usr/share/jenkins/agent.jar \
  -url http://jenkins-controller:8080 \
  -secret <secret> \
  -name <agent-name>

Default CMD difference

The DOI default CMD is ["bash"] while the DHI default CMD is ["/usr/bin/java","-jar","/usr/share/jenkins/agent.jar"]. If your setup relies on the DOI default, update your command or args fields in Kubernetes manifests or your docker run command accordingly.

Java path

The DHI JAVA_HOME is /usr/lib/jvm/temurin-21 while the DOI JAVA_HOME is /opt/java/openjdk. Update any scripts or environment variables that reference JAVA_HOME directly.

No package manager

The runtime image does not include a package manager. If your build jobs require additional tools, use the dev image variant as a build stage and copy the required binaries to the runtime stage.

Entry point

Docker Hardened Images may have different entry points than images such as Docker Official Images. Use docker inspect to inspect entry points for Docker Hardened Images and update your Dockerfile if necessary.