### Install Docker BuildX Plugin

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Use this command to install and set up the Docker BuildX plugin, which is required for certain build processes.

```bash
docker buildx create --use --bootstrap --driver docker-container
```

--------------------------------

### Install Required Tools for Adoption Scripts (Debian)

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Install curl and jq on Debian-based systems using apt-get, which are required by adoption scripts.

```dockerfile
# Debian
RUN apt-get install -y curl jq
```

--------------------------------

### Buildx Bake Command Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

An example of the docker buildx bake command used for building images, specifying platforms and loading the result.

```bash
docker buildx bake --load --set '*.platform=$(OS)/$(ARCH)' <targets>
```

--------------------------------

### PowerShell Build Script Usage Examples

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Examples demonstrate building all Windows images, specific image or agent types, and using dry run mode.

```powershell
.\make.ps1
```

```powershell
.\make.ps1 -ImageType "nanoserver-ltsc2022"
```

```powershell
.\make.ps1 -AgentType "inbound-agent"
```

```powershell
.\make.ps1 -DryRun
```

```powershell
.\make.ps1 -TestsDebug 'debug'
```

--------------------------------

### TARGETPLATFORM Format Examples

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Illustrates the OS/ARCH or OS/ARCH/VARIANT format for TARGETPLATFORM, provided by Docker buildkit. Used for conditional logic in Dockerfiles.

```text
linux/amd64
linux/arm64
linux/arm/v7
windows/amd64
windows/arm64
```

--------------------------------

### JAVA_VERSION Format Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Illustrates the MAJOR.MINOR.PATCH_UPDATE format for Java versions. Used for Docker build ARG JAVA_VERSION, Adoptium API, and JDK installation paths.

```text
17.0.19_10
21.0.11_10
25.0.3_9
```

--------------------------------

### Install Required Tools for Adoption Scripts (Alpine)

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Install curl and jq on Alpine Linux using apk, which are required by adoption scripts.

```dockerfile
# Alpine
RUN apk add --no-cache curl jq
```

--------------------------------

### UBI9_TAG Format Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Shows the MAJOR.MINOR-BUILDID format for Red Hat UBI9 tags. Used for Docker build ARG UBI9_TAG.

```text
9.8-1781496985
```

--------------------------------

### Basic Inbound Connection Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Demonstrates a standard inbound connection to Jenkins using the agent container. Requires URL, secret, and agent name.

```bash
docker run --init jenkins/inbound-agent -url http://jenkins:8080 mysecret myagent
```

--------------------------------

### Docker Bake Target Definition Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

An example of a target definition for building an Alpine-based agent image, specifying matrix, name, Dockerfile, context, arguments, tags, and platforms.

```hcl
target "alpine" {
  matrix = {
    type = agent_types_to_build  # ["agent", "inbound-agent"]
    jdk  = jdks_to_build          # [17, 21, 25]
  }
  name       = "${type}_alpine_jdk${jdk}"
  target     = type               # agent or inbound-agent stage
  dockerfile = "alpine/Dockerfile"
  context    = "."
  args = {
    ALPINE_TAG      = ALPINE_FULL_TAG
    JAVA_VERSION    = jdk_versions[jdk]
    VERSION         = REMOTING_VERSION
  }
  tags = [
    "${REGISTRY}/${REGISTRY_ORG}/${REGISTRY_REPO_AGENT}:alpine",
    "${REGISTRY}/${REGISTRY_ORG}/${REGISTRY_REPO_AGENT}:alpine-jdk${jdk}",
    # ... additional tags
  ]
  platforms = ["linux/amd64", "linux/arm64", "linux/arm/v7"]
}
```

--------------------------------

### Direct TCP Connection Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Establishes a direct TCP connection to Jenkins without HTTP negotiation by setting JENKINS_DIRECT_CONNECTION.

```bash
docker run --init \
  -e JENKINS_DIRECT_CONNECTION=jenkins:50000 \
  jenkins/inbound-agent \
  mysecret myagent
```

--------------------------------

### RELEASE_TAG Format Example (Alpine)

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Demonstrates the MAJOR.MINOR.PATCH format for Alpine release tags. Used for Docker build ARG ALPINE_TAG.

```text
3.24.0
```

--------------------------------

### jdks_to_build Variable Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Defines a list of major Java versions to build. Used in the matrix to generate targets like agent_alpine_jdk17.

```hcl
variable "jdks_to_build" {
  default = [17, 21, 25]
}
```

--------------------------------

### RELEASE_STRING Format Example (Debian)

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Presents the CODENAME-DATESTRING format for Debian release strings. Used for Docker build ARG DEBIAN_RELEASE.

```text
trixie-20260610
```

--------------------------------

### Remoting Options Quoting Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Demonstrates correct and incorrect quoting for the REMOTING_OPTS environment variable to prevent unintended shell expansion.

```bash
# Correct: quotes are preserved
-e REMOTING_OPTS="-Dsome.property='value with spaces'"

# Incorrect: will expand $var
-e REMOTING_OPTS="-Dsome.property=$var"
```

--------------------------------

### Adoptium JDK Install Script Signature

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

The adoptium-install-jdk.sh script downloads and installs a JDK. It optionally takes an OS parameter and requires the JAVA_VERSION environment variable.

```bash
./adoptium-install-jdk.sh [os]
```

--------------------------------

### WebSocket Connection Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Enables WebSocket protocol for the agent connection by setting the JENKINS_WEB_SOCKET environment variable.

```bash
docker run --init \
  -e JENKINS_WEB_SOCKET=true \
  jenkins/inbound-agent \
  -url http://jenkins:8080 \
  mysecret myagent
```

--------------------------------

### Validate Java Options Syntax

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Check the syntax of Java options to prevent startup errors. Examples show valid and invalid formats.

```bash
# Valid
-Xmx512m -XX:+UseG1GC

# Invalid
-Xmx 512m  # Space before value
-XX+UseG1GC  # Missing colon
```

--------------------------------

### Instance Identity Authentication Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Uses instance identity for authentication, bypassing standard HTTP port negotiation. Requires JENKINS_INSTANCE_IDENTITY and JENKINS_PROTOCOLS.

```bash
docker run --init \
  -e JENKINS_INSTANCE_IDENTITY=base64_encoded_identity \
  -e JENKINS_PROTOCOLS=JNLP4-connect \
  jenkins/inbound-agent \
  -url http://jenkins:8080 \
  mysecret myagent
```

--------------------------------

### Kubernetes Pod/Container Spec Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

Example Kubernetes pod specification for running a Jenkins inbound agent. It includes environment variables for Jenkins URL, secret, agent name, JVM options, and volume mounts.

```yaml
containers:
- name: jenkins-agent
  image: jenkins/inbound-agent:jdk21
  env:
  - name: JENKINS_URL
    value: http://jenkins:8080
  - name: JENKINS_SECRET
    valueFrom:
      secretKeyRef:
        name: jenkins-agent
        key: secret
  - name: JENKINS_AGENT_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: JENKINS_JAVA_OPTS
    value: "-Xmx512m"
  volumeMounts:
  - name: jenkins-home
    mountPath: /home/jenkins/.jenkins
  - name: jenkins-work
    mountPath: /home/jenkins/agent
volumes:
- name: jenkins-home
  emptyDir: {}
- name: jenkins-work
  emptyDir: {}
```

--------------------------------

### VERSION (Remoting Version) Format Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Shows the REVISION.vHASH format for Remoting versions, combining a numeric revision with a Git commit hash. Used for Docker build ARG VERSION and agent.jar.

```text
3355.v388858a_47b_33
```

--------------------------------

### Set Valid JAVA_VERSION Format

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Ensure the JAVA_VERSION argument follows the MAJOR.MINOR.PATCH_UPDATE format. The example shows a correct and an incorrect format.

```dockerfile
ARG JAVA_VERSION=17.0.19_10    # Correct
ARG JAVA_VERSION=17.0.19       # Incorrect - missing update number
```

--------------------------------

### Bash Script for Linux Agent Entry Point

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/INDEX.md

The jenkins-agent Bash script is the entry point for configuring and launching the agent.jar on Linux systems. It handles setup before the agent connects to Jenkins.

```bash
# jenkins-agent (Bash)
# Configures and launches agent.jar on Linux

set -e

# Default values
JENKINS_URL="http://jenkins:8080"
AGENT_WORKDIR="/home/jenkins/agent"

# Parse environment variables or command-line arguments
# Example: export JENKINS_URL=http://myjenkins.com
# Example: ./jenkins-agent --url http://myjenkins.com --workdir /tmp/agent

# Function to display usage
usage() {
    echo "Usage: $0 [--url JENKINS_URL] [--workdir AGENT_WORKDIR]"
    exit 1
}

# Parse arguments
while [[ "$#" -gt 0 ]]; do
    key="$1"
    case $key in
        --url)
        JENKINS_URL="$2"
        shift # past argument
        shift # past value
        ;;
        --workdir)
        AGENT_WORKDIR="$2"
        shift # past argument
        shift # past value
        ;;
        -h|--help)
        usage
        ;;
        *)
        echo "Unknown option: $1"
        usage
        ;;
    esac
done

# Ensure agent work directory exists
mkdir -p "$AGENT_WORKDIR"
cd "$AGENT_WORKDIR"

# Download agent.jar if it doesn't exist
if [ ! -f "agent.jar" ]; then
    echo "Downloading agent.jar from $JENKINS_URL..."
    # In a real scenario, you would download from a stable URL, e.g., Jenkins controller
    # For this example, we'll assume it's available or downloaded elsewhere.
    echo "Placeholder: Download agent.jar"
    # Example: curl -o agent.jar http://your-jenkins-url/jnlpJars/agent.jar
fi

# Execute agent.jar
echo "Starting Jenkins agent..."
echo "Jenkins URL: $JENKINS_URL"
echo "Agent Work Directory: $AGENT_WORKDIR"

java -jar agent.jar -jnlpUrl $JENKINS_URL/computer/your-agent-name/slave-agent.jnlp -workDir $AGENT_WORKDIR

echo "Jenkins agent stopped."

```

--------------------------------

### agent_types_to_build Variable Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Defines a list of agent types to build, specifying base agent and inbound-agent images. Used in the docker-bake.hcl matrix.

```hcl
variable "agent_types_to_build" {
  default = ["agent", "inbound-agent"]
}
```

--------------------------------

### jdk_versions Variable Example

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/types.md

Maps JDK major versions to their full version strings for the Dockerfile ARG JAVA_VERSION. Provides specific version details for builds.

```hcl
variable "jdk_versions" {
  default = {
    17 = "17.0.19_10"
    21 = "21.0.11_10"
    25 = "25.0.3_9"
  }
}
```

--------------------------------

### Show Available Architectures

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

This command lists the supported architectures for the build. Use it to check platform compatibility when encountering 'Platform Not Supported' errors.

```bash
make showarch-arm64
```

--------------------------------

### Recommended REMOTING_OPTS Usage

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Illustrates the recommended way to configure agent options using the REMOTING_OPTS environment variable for increased flexibility.

```bash
-e REMOTING_OPTS="-url http://jenkins:8080 -logger DEBUG"
```

--------------------------------

### Show Docker Build Information

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Execute `make show` to display detailed information about images that can be built. This command internally uses `docker buildx bake` and `jq` to process and present the build configurations. Set `ON_TAG=true` to include all tags created during publication.

```bash
$ make show
+ make --silent show-all
+ docker buildx bake --file docker-bake.hcl --progress=quiet --print all
+ jq
{
  "group": {
    "alpine": {
      "targets": [
        "agent_alpine_jdk17",
        "agent_alpine_jdk21",
        "inbound-agent_alpine_jdk17",
        "inbound-agent_alpine_jdk21"
      ]
    },
    "debian": {
      "targets": [
        "agent_debian_jdk17",
        "agent_debian_jdk21",
        "inbound-agent_debian_jdk17",
        "inbound-agent_debian_jdk21"
      ]
    },
    "default": {
      "targets": [
        "linux"
      ]
    },
    "linux": {
      "targets": [
        "alpine",
        "debian",
        "rhel_ubi9"
      ]
    },
    "rhel_ubi9": {
      "targets": [
        "agent_rhel_ubi9_jdk17",
        "agent_rhel_ubi9_jdk21",
        "inbound-agent_rhel_ubi9_jdk17",
        "inbound-agent_rhel_ubi9_jdk21"
      ]
    }
  },
  "target": {
    "agent_alpine_jdk17": {
      "context": ".",
      "dockerfile": "alpine/Dockerfile",
      "args": {
        "ALPINE_TAG": "3.24.0",
        "JAVA_VERSION": "17.0.19_10",
        "VERSION": "3355.v388858a_47b_33"
      },
      "tags": [
        "docker.io/jenkins/agent:alpine",
        "docker.io/jenkins/agent:latest-alpine",
        "docker.io/jenkins/agent:alpine-jdk17",
        "docker.io/jenkins/agent:latest-alpine-jdk17",
        "docker.io/jenkins/agent:alpine3.24",
        "docker.io/jenkins/agent:latest-alpine3.24",
        "docker.io/jenkins/agent:alpine3.24-jdk17",
        "docker.io/jenkins/agent:latest-alpine3.24-jdk17"
      ],
      "target": "agent",
      "platforms": [
        "linux/amd64"
      ],
      "output": [
        {
          "type": "docker"
        }
      ]
    },
    [...]
  }
}

```

--------------------------------

### Prepare Test Environment

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Prepares the test environment by cloning/updating BATS, updating git submodules, and creating the target directory.

```bash
make prepare-test
```

--------------------------------

### Inbound Connection Using Environment Variables

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Sets up the agent connection using environment variables for URL, secret, agent name, and Java options.

```bash
docker run --init \
  -e JENKINS_URL=http://jenkins:8080 \
  -e JENKINS_SECRET=mysecret \
  -e JENKINS_AGENT_NAME=myagent \
  -e JENKINS_JAVA_OPTS="-Xmx512m" \
  jenkins/inbound-agent
```

--------------------------------

### Show All Target Configurations

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Displays detailed configuration for all build targets, including full tag lists, platforms, and build arguments. The output is in JSON format derived from docker-bake.hcl.

```bash
make show
```

--------------------------------

### Running Agent JAR Help Command

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Shows how to execute the agent.jar help command using a Docker container when running in daemon mode.

```bash
docker run --rm --entrypoint= jenkins/inbound-agent java -jar /usr/share/jenkins/agent.jar -help
```

--------------------------------

### Show Specific Target Configuration

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Displays the configuration for a specific build target.

```bash
make show-agent_alpine_jdk21
```

--------------------------------

### Initialize Docker for CI/CD

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Initializes Docker for CI/CD environments, specifically for Jenkins infrastructure. Creates a docker buildx builder with optional buildkitd configuration.

```bash
make docker-init
```

--------------------------------

### Set JAVA_HOME Environment Variable

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Set the JAVA_HOME environment variable to resolve 'Java Not Found' errors in PowerShell. This points the system to your Java installation directory.

```powershell
$env:JAVA_HOME = "C:\Program Files\Java\jdk-21"
."/jenkins-agent.ps1" -Url ... -Secret ... -Name ...
```

--------------------------------

### Agent Launch with Positional Arguments and Explicit URL

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Demonstrates launching the agent with positional arguments for secret and name, and explicitly specifying the controller URL.

```powershell
.\jenkins-agent.ps1 "my-secret" "my-agent" -Url http://jenkins:8080
```

--------------------------------

### Set JAVA_HOME for jenkins-agent

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

If the Java executable is not found in the system's PATH, set the JAVA_HOME environment variable to the correct Java installation directory before running the jenkins-agent script.

```bash
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
jenkins-agent -url http://jenkins:8080 -secret ... -name ...
```

--------------------------------

### Set Valid Timezone (TZ)

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Use valid POSIX timezone names for the TZ environment variable to ensure correct timezone operations. Examples show valid and invalid formats.

```bash
# Valid
-e TZ=Europe/Paris
-e TZ=America/New_York

# Invalid
-e TZ=EST  # Use America/New_York instead
```

--------------------------------

### Dockerfile for Setting Timezone

Source: https://github.com/jenkinsci/docker-agents/blob/master/README_agent.md

Example Dockerfile snippet demonstrating how to set the timezone within a custom image based on 'jenkins/agent'. It uses the 'TZ' environment variable and configures timezone data.

```dockerfile
FROM jenkins/agent as agent
 [...] 
ENV TZ=Asia/Shanghai
 [...] 
RUN ln -snf /usr/share/zoneinfo/"${TZ}" /etc/localtime && echo "${TZ}" > /etc/timezone \
    && dpkg-reconfigure -f noninteractive tzdata \
 [...] 
```

--------------------------------

### List Targets for Specific Architecture

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists all build targets available for a specified architecture.

```bash
make listarch-arm64
```

--------------------------------

### List Groups for Specific OS

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists all build groups available for a specified operating system.

```bash
make listgroup-linux
```

--------------------------------

### Generate Windows Docker Compose File

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Generates a Windows Docker Compose file from docker-bake.hcl using docker buildx bake and yq. This command requires docker buildx and yq to be installed.

```bash
$ docker buildx bake --progress=quiet --file=docker-bake.hcl windows --print \
    | yq --prettyPrint '.target[] | del(.output) | {(. | key): {"image": .tags[0], "build": .}}' | yq '{"services": .}' \
    > build-windows_mybuild.yaml
```

--------------------------------

### List Target Images for Current OS and Architecture

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Lists all target Docker agent images that match your current operating system and architecture. This command uses `make list` which internally calls `make show-all` and `jq` to filter the output.

```bash
$ make list
+ make --silent listarch-arm64
+ make --silent showarch-arm64
+ jq -r '.target | keys[]'
+ make --silent show
+ jq --arg arch linux/arm64 '.target |= with_entries(select(.value.platforms | index($arch)))'
+ make --silent show-all
+ docker buildx bake --file docker-bake.hcl --progress=quiet --print all
+ jq
agent_alpine_jdk21
agent_alpine_jdk25
agent_debian_jdk17
agent_debian_jdk21
agent_debian_jdk25
agent_rhel_ubi9_jdk17
agent_rhel_ubi9_jdk21
agent_rhel_ubi9_jdk25
inbound-agent_alpine_jdk21
inbound-agent_alpine_jdk25
inbound-agent_debian_jdk17
inbound-agent_debian_jdk21
inbound-agent_debian_jdk25
inbound-agent_rhel_ubi9_jdk17
inbound-agent_rhel_ubi9_jdk21
inbound-agent_rhel_ubi9_jdk25
```

--------------------------------

### Build All Images

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Builds all Docker images for the current operating system and architecture.

```bash
make build
```

--------------------------------

### Show Targets for Specific Architecture

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Displays all build targets available for a specified architecture, filtering by platform availability.

```bash
make showarch-amd64
```

--------------------------------

### List Windows Agent Tags

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Lists available Docker image tags for Windows-based agents, including Nano Server and Server Core variants with different JDK versions. Use this to select the appropriate Windows agent image.

```bash
make tags-windows
```

--------------------------------

### Build Script Test Target

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

To run tests, use the '-t test' option. This will first build the images and then execute the tests.

```bash
./build.sh -t test
```

--------------------------------

### Multi-Architecture Build for a Group

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Builds a specific group of images across all supported architectures.

```bash
make multiarchbuild-alpine
```

--------------------------------

### Check Prerequisites

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Validates the presence of required tools like bash, git, docker, docker buildx plugin, curl, and jq.

```bash
make check-reqs
```

--------------------------------

### List Targets for Current Architecture

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists all build targets available for the current architecture. This is equivalent to `make listarch-$(ARCH)`.

```bash
make list
```

--------------------------------

### Build and Test Docker Agent Image

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Ensure an image is built before attempting to test it. Use these make commands to build and then test a specific agent image.

```bash
make build-agent_alpine_jdk21
make test-agent_alpine_jdk21
```

--------------------------------

### List All Target Images

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Lists all available target Docker agent images, regardless of the current architecture. This command uses `make list-all` which internally calls `make show-all` and `jq`.

```bash
$ make list-all
+ make --silent show-all
+ jq -r '.target | keys[]'
+ docker buildx bake --file docker-bake.hcl --progress=quiet --print all
+ jq
agent_alpine_jdk17
agent_alpine_jdk21
agent_alpine_jdk25
agent_debian_jdk17
agent_debian_jdk21
agent_debian_jdk25
agent_nanoserver-ltsc2019_jdk17
agent_nanoserver-ltsc2019_jdk21
agent_nanoserver-ltsc2019_jdk25
agent_nanoserver-ltsc2022_jdk17
agent_nanoserver-ltsc2022_jdk21
agent_nanoserver-ltsc2022_jdk25
agent_rhel_ubi9_jdk17
agent_rhel_ubi9_jdk21
agent_rhel_ubi9_jdk25
agent_windowsservercore-ltsc2019_jdk17
agent_windowsservercore-ltsc2019_jdk21
agent_windowsservercore-ltsc2019_jdk25
agent_windowsservercore-ltsc2022_jdk17
agent_windowsservercore-ltsc2022_jdk21
agent_windowsservercore-ltsc2022_jdk25
inbound-agent_alpine_jdk17
inbound-agent_alpine_jdk21
inbound-agent_alpine_jdk25
inbound-agent_debian_jdk17
inbound-agent_debian_jdk21
inbound-agent_debian_jdk25
inbound-agent_nanoserver-ltsc2019_jdk17
inbound-agent_nanoserver-ltsc2019_jdk21
inbound-agent_nanoserver-ltsc2019_jdk25
inbound-agent_nanoserver-ltsc2022_jdk17
inbound-agent_nanoserver-ltsc2022_jdk21
inbound-agent_nanoserver-ltsc2022_jdk25
inbound-agent_rhel_ubi9_jdk17
inbound-agent_rhel_ubi9_jdk21
inbound-agent_rhel_ubi9_jdk25
inbound-agent_windowsservercore-ltsc2019_jdk17
inbound-agent_windowsservercore-ltsc2019_jdk21
inbound-agent_windowsservercore-ltsc2019_jdk25
inbound-agent_windowsservercore-ltsc2022_jdk17
inbound-agent_windowsservercore-ltsc2022_jdk21
inbound-agent_windowsservercore-ltsc2022_jdk25
```

--------------------------------

### Agent Launch with Java Heap Options

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Configures the agent launch with specific Java heap size and other JVM options using -JenkinsJavaOpts.

```powershell
.\jenkins-agent.ps1 `
  -Url http://jenkins:8080 `
  -Secret "my-secret" `
  -Name "my-agent" `
  -JenkinsJavaOpts "-Xmx1024m -XX:+UseStringDeduplication"
```

--------------------------------

### Agent Launch with Direct TCP Connection

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Establishes a direct TCP connection to the Jenkins controller using the -DirectConnection parameter.

```powershell
.\jenkins-agent.ps1 `
  -Secret "my-secret" `
  -Name "my-agent" `
  -DirectConnection "jenkins:50000"
```

--------------------------------

### Agent Launch with WebSocket Connection

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Enables WebSocket protocol for agent connection by using the -WebSocket switch parameter.

```powershell
.\jenkins-agent.ps1 `
  -Url http://jenkins:8080 `
  -Secret "my-secret" `
  -Name "my-agent" `
  -WebSocket
```

--------------------------------

### Launch Java Process

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

The script launches the Java process for the agent using `Start-Process`. The `-Wait` and `-NoNewWindow` parameters control process behavior.

```powershell
Start-Process -FilePath $JAVA_BIN `
  -Wait `
  -NoNewWindow `
  -ArgumentList $AgentArguments
```

--------------------------------

### List All Image Tags

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists all image tags for the current OS targets. The output format is `image:tag (target_name)`.

```bash
make tags
```

--------------------------------

### Makefile OS and ARCH Auto-Detection

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Demonstrates how the Makefile automatically detects the current operating system and architecture using shell commands.

```makefile
current_os := $(shell uname -s)
# Maps: Linux→linux, Darwin→linux, MINGW/MSYS/CYGWIN→windows

current_arch := $(shell uname -m)
```

--------------------------------

### Build Script Usage

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

The build.sh script accepts options for target, remoting version, and build number. The target can be build, test, or publish.

```bash
./build.sh [-t target] [-r remoting_version] [-b build_number]
```

--------------------------------

### Publish All Images

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Publishes all Docker images for the current OS to the registry. This command uses docker buildx with the --push flag and requires registry authentication.

```bash
make publish
```

--------------------------------

### Basic Agent Launch with Default Parameters

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Launches the Jenkins agent using default parameters, requiring only the secret and agent name as positional arguments.

```powershell
.\jenkins-agent.ps1 <secret> <agent_name>
```

--------------------------------

### List Target Images for Specific OS and Architecture

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Lists target Docker agent images for a specified operating system and architecture. This is useful for cross-platform development or testing. The command sets `OS` and `ARCH` environment variables before running `make list`.

```bash
$ OS=windows ARCH=amd64 make list
+ make --silent listarch-amd64
+ make --silent showarch-amd64
+ jq -r '.target | keys[]'
+ make --silent show
+ jq --arg arch windows/amd64 '.target |= with_entries(select(.value.platforms | index($arch)))'
+ make --silent show-all
+ docker buildx bake --file docker-bake.hcl --progress=quiet --print all
+ jq
agent_nanoserver-ltsc2019_jdk17
agent_nanoserver-ltsc2019_jdk21
agent_nanoserver-ltsc2019_jdk25
agent_nanoserver-ltsc2022_jdk17
agent_nanoserver-ltsc2022_jdk21
agent_nanoserver-ltsc2022_jdk25
agent_windowsservercore-ltsc2019_jdk17
agent_windowsservercore-ltsc2019_jdk21
agent_windowsservercore-ltsc2019_jdk25
agent_windowsservercore-ltsc2022_jdk17
agent_windowsservercore-ltsc2022_jdk21
agent_windowsservercore-ltsc2022_jdk25
inbound-agent_nanoserver-ltsc2019_jdk17
inbound-agent_nanoserver-ltsc2019_jdk21
inbound-agent_nanoserver-ltsc2019_jdk25
inbound-agent_nanoserver-ltsc2022_jdk17
inbound-agent_nanoserver-ltsc2022_jdk21
inbound-agent_nanoserver-ltsc2022_jdk25
inbound-agent_windowsservercore-ltsc2019_jdk17
inbound-agent_windowsservercore-ltsc2019_jdk21
inbound-agent_windowsservercore-ltsc2019_jdk25
inbound-agent_windowsservercore-ltsc2022_jdk17
inbound-agent_windowsservercore-ltsc2022_jdk21
inbound-agent_windowsservercore-ltsc2022_jdk25
```

--------------------------------

### List Tags for Specific Target

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists image tags for a specific build target. The output format is `image:tag (target_name)`.

```bash
make tags-agent_alpine_jdk21
```

--------------------------------

### Basic Agent Launch with Positional Arguments

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Launches the Jenkins agent using positional arguments for secret and agent name, along with the controller URL.

```powershell
.\jenkins-agent.ps1 -Url http://jenkins -Secret <secret> -Name <agent_name>
```

--------------------------------

### Agent Launch with Named Parameters

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Launches the agent using explicit named parameters for URL, secret, and agent name.

```powershell
.\jenkins-agent.ps1 `
  -Url http://jenkins:8080 `
  -Secret "my-secret" `
  -Name "my-agent"
```

--------------------------------

### List Docker Bake Targets

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/errors.md

Run these commands to list available targets in your docker-bake.hcl file, helping to resolve 'image or group does not exist' errors.

```bash
# List available targets for your architecture
make list

# or list all
make list-all
```

--------------------------------

### Build Script Publish Target

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

The publish target requires specifying the remoting version and build number. It exports the remoting version, sets ON_TAG and BUILD_NUMBER, and then pushes images.

```bash
./build.sh -t publish -r 3355.v388858a_47b_33 -b 3
```

--------------------------------

### Makefile Targets for Docker Agent Builds

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/docker-images.md

Provides common Makefile targets for building, showing configuration, and testing Docker agent images. Use 'build-IMAGENAME' to build a specific image or 'show-GROUPNAME' to display configuration for a group.

```makefile
make build              # Build for current OS/architecture
make build-IMAGENAME    # Build specific image
make multiarchbuild     # Build all for current OS (multiple architectures)

make show               # Show current build targets
make show-GROUPNAME     # Show specific group

make test               # Test for current OS
make test-IMAGENAME     # Test specific image
```

--------------------------------

### Configure SELinux Volume Mount

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

Configure volume mounts with SELinux context for persistent storage. The ':Z' option applies a shared content label, allowing multiple containers to access the volume.

```bash
docker run \
  -v jenkins-home:/home/jenkins/.jenkins:Z \
  jenkins/inbound-agent ...
```

--------------------------------

### Initialize Git LFS System-Wide

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

This command initializes Git Large File Storage (LFS) system-wide. It should be run once to ensure Git LFS is available for all repositories on the system.

```bash
git lfs install --skip-repo --system
```

--------------------------------

### Agent with Extra Remoting Options

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Passes additional command-line options directly to the agent.jar process using the REMOTING_OPTS environment variable.

```bash
docker run --init \
  -e REMOTING_OPTS="-logger WARNING" \
  jenkins/inbound-agent \
  -url http://jenkins:8080 \
  mysecret myagent
```

--------------------------------

### Adoptium JDK Link Script Signature

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

The adoptium-get-jdk-link.sh script fetches JDK download URLs. It requires the Java version and OS, with optional architectures.

```bash
./adoptium-get-jdk-link.sh <java_version> <os> [architectures]
```

--------------------------------

### Multi-Architecture Build

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Builds all Docker images for the current operating system across all supported architectures. This command uses docker buildx without the --load flag, directing output to the Docker daemon or registry.

```bash
make multiarchbuild
```

--------------------------------

### Run Jenkins Agent with Work Directory (Linux)

Source: https://github.com/jenkinsci/docker-agents/blob/master/README_agent.md

Launches a Jenkins agent container on Linux, mounting a volume for the work directory to manage logs and caching. Uses the agent.jar executable.

```sh
docker run -i --rm --name agent1 --init -v agent1-workdir:/home/jenkins/agent jenkins/agent java -jar /usr/share/jenkins/agent.jar -workDir /home/jenkins/agent
```

--------------------------------

### Agent Launch with Custom Work Directory

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-powershell.md

Specifies a custom working directory for the agent using the -WorkDir parameter.

```powershell
.\jenkins-agent.ps1 `
  -Url http://jenkins:8080 `
  -Secret "my-secret" `
  -Name "my-agent" `
  -WorkDir "C:/Jenkins/work"
```

--------------------------------

### Build a Specific Docker Agent Image

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Builds a single, specific Docker agent image. The command follows the pattern `make build-<AGENT_TYPE>_<LINUX_FLAVOR>_<JDK_VERSION>`.

```bash
make build-<AGENT_TYPE>_<LINUX_FLAVOR>_<JDK_VERSION>
```

```bash
make build-inbound-agent_debian_jdk17
```

--------------------------------

### Run Build Script with Debugging on Windows

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Execute the build script with verbose debugging output on Windows. This helps diagnose build failures specific to the Windows environment.

```powershell
$VerbosePreference = 'Continue'
.\make.ps1 -DryRun
```

--------------------------------

### Build Script Default Target

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

To execute the default build target, simply run the script without any arguments or explicitly specify the 'build' target.

```bash
./build.sh
# or
./build.sh -t build
```

--------------------------------

### Run Jenkins Agent Docker Container (Linux)

Source: https://github.com/jenkinsci/docker-agents/blob/master/README_agent.md

Launches a Jenkins agent container on Linux using the 'jenkins/agent' image. Sets up a remote root directory for agent operations.

```sh
docker run -i --rm --name agent --init jenkins/agent java -jar /usr/share/jenkins/agent.jar
```

--------------------------------

### Run Jenkins Agent with Work Directory (Windows)

Source: https://github.com/jenkinsci/docker-agents/blob/master/README_agent.md

Launches a Jenkins agent container on Windows, mounting a volume for the work directory. Uses a specific JDK tag and the agent.jar executable.

```powershell
docker run -i --rm --name agent1 --init -v agent1-workdir:C:/Users/jenkins/Work jenkins/agent:jdk17-windowsservercore-ltsc2019 java -jar C:/ProgramData/Jenkins/agent.jar -workDir C:/Users/jenkins/Work
```

--------------------------------

### Build Docker Image with Variable Overrides

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

Use this command to build a Docker image, overriding default variables with environment variables. Ensure all necessary environment variables are exported before execution.

```bash
export REMOTING_VERSION="3355.v388858a_47b_33"
export ALPINE_FULL_TAG="3.24.0"
export DEBIAN_RELEASE="trixie-20260610"
export BUILD_NUMBER="3"
export ON_TAG="true"
docker buildx bake --file docker-bake.hcl linux
```

--------------------------------

### PowerShell Script for Windows Agent Entry Point

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/INDEX.md

The jenkins-agent.ps1 PowerShell script serves as the entry point for Windows, configuring and launching agent.jar. It ensures the agent is set up correctly before connecting to Jenkins.

```powershell
# jenkins-agent.ps1 (PowerShell)
# Configures and launches agent.jar on Windows

param(
    [string]$JenkinsUrl = "http://jenkins:8080",
    [string]$AgentWorkDir = "C:\\Users\\jenkins\\agent"
)

Write-Host "Starting Jenkins agent configuration on Windows..."

# Ensure agent work directory exists
if (-not (Test-Path -Path $AgentWorkDir -PathType Container)) {
    New-Item -Path $AgentWorkDir -ItemType Directory -Force | Out-Null
    Write-Host "Created agent work directory: $AgentWorkDir"
}

Set-Location -Path $AgentWorkDir

# Download agent.jar if it doesn't exist
$agentJarPath = Join-Path -Path $AgentWorkDir -ChildPath "agent.jar"
if (-not (Test-Path -Path $agentJarPath -PathType Leaf)) {
    Write-Host "Downloading agent.jar from Jenkins controller..."
    # In a real scenario, download from Jenkins controller
    # Example: Invoke-WebRequest -Uri "$JenkinsUrl/jnlpJars/agent.jar" -OutFile $agentJarPath
    Write-Host "Placeholder: Download agent.jar"
}

# Execute agent.jar
Write-Host "Starting Jenkins agent..."
Write-Host "Jenkins URL: $JenkinsUrl"
Write-Host "Agent Work Directory: $AgentWorkDir"

# Example command to run agent.jar. Adjust parameters as needed.
# java -jar $agentJarPath -jnlpUrl $JenkinsUrl/computer/your-agent-name/slave-agent.jnlp -workDir $AgentWorkDir
Write-Host "Simulating agent.jar execution."

Write-Host "Jenkins agent process finished."

```

--------------------------------

### List Targets in a Specific Group

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lists all build targets within a specified group.

```bash
make list-alpine
```

--------------------------------

### Agent with Custom Java Options

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Specifies custom Java Virtual Machine options for the agent process using JENKINS_JAVA_OPTS.

```bash
docker run --init \
  -e JENKINS_JAVA_OPTS="-Xmx1024m -XX:+UseStringDeduplication" \
  jenkins/inbound-agent \
  -url http://jenkins:8080 \
  mysecret myagent
```

--------------------------------

### Inbound Connection with Custom Work Directory

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/jenkins-agent-bash.md

Configures a specific work directory for the agent using a volume mount and the -workDir option.

```bash
docker run --init -v agent-work:/home/jenkins/agent \
  jenkins/inbound-agent \
  -url http://jenkins:8080 \
  -workDir /home/jenkins/agent \
  mysecret myagent
```

--------------------------------

### Configure jlink for Java Modules

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

This command is used to create a custom Java runtime image using jlink. It includes all standard Java modules and applies compression for a smaller footprint.

```bash
jlink --add-modules ALL-MODULE-PATH --compress=2
```

--------------------------------

### Lint Dockerfiles

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/api-reference/build-system.md

Lints all Dockerfiles for best practices using the `tools/hadolint` wrapper script.

```bash
make hadolint
```

--------------------------------

### Configure Java HTTP Proxy

Source: https://github.com/jenkinsci/docker-agents/blob/master/_autodocs/configuration.md

Set Java system properties to configure an HTTP proxy for the agent. This is useful when the agent needs to access external resources through a proxy.

```bash
docker run \
  -e JENKINS_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" \
  jenkins/inbound-agent -url ... -secret ... -name ...
```

--------------------------------

### View Docker Agent Tags

Source: https://github.com/jenkinsci/docker-agents/blob/master/README.md

Set ON_TAG to true and specify a BUILD_NUMBER to list all available Docker agent tags. This command is useful for understanding the different image variants and their corresponding labels.

```bash
$ ON_TAG=true BUILD_NUMBER=3 make tags
```