Agent availability and offline handling in Jenkins - Commands & Configuration

Introduction

Jenkins uses agents to run tasks. Sometimes agents go offline or become unavailable. Managing agent availability helps keep your builds running smoothly without interruptions.

When a build job is stuck because the assigned agent is offline.

When you want to check which agents are ready to run jobs.

When you need to bring an offline agent back online to continue work.

When you want to temporarily disable an agent for maintenance.

When you want Jenkins to automatically handle offline agents to avoid build failures.

Commands

This command starts a Jenkins agent by connecting it to the Jenkins master using the JNLP URL and secret key. It brings the agent online so it can run jobs.

Terminal

java -jar agent.jar -jnlpUrl http://localhost:8080/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef

Expected Output

[Jenkins agent] Connecting to http://localhost:8080/computer/my-agent/slave-agent.jnlp

[Jenkins agent] Connected

[Jenkins agent] Agent successfully connected and online

→

-jnlpUrl - Specifies the URL to connect the agent to the Jenkins master

→

-secret - Provides the secret key for secure authentication

This command disconnects the Jenkins agent from the master, making it go offline. Use this to safely take an agent offline for maintenance.

Terminal

java -jar agent.jar -disconnect

Expected Output

[Jenkins agent] Disconnecting from Jenkins master

[Jenkins agent] Agent disconnected and offline

This command toggles the offline status of the agent named 'my-agent' using Jenkins REST API. It can bring the agent online or offline remotely.

Terminal

curl -X POST http://localhost:8080/computer/my-agent/toggleOffline

Expected Output

No output (command runs silently)

→

-X POST - Sends a POST request to change the agent status

Starts the Jenkins agent with a specified working directory. This helps organize files and logs for the agent.

Terminal

java -jar agent.jar -jnlpUrl http://localhost:8080/computer/my-agent/slave-agent.jnlp -secret 1234567890abcdef -workDir "."

Expected Output

[Jenkins agent] Connecting to http://localhost:8080/computer/my-agent/slave-agent.jnlp

[Jenkins agent] Connected

[Jenkins agent] Agent successfully connected and online

→

-workDir - Sets the working directory for the agent files

Key Concept

If you remember nothing else from this pattern, remember: keeping Jenkins agents online and properly connected ensures your build jobs run without interruption.

Common Mistakes

Trying to run jobs on an agent that is offline.

The job will fail or stay queued because the agent is not available to execute it.

Check agent status and bring the agent online before running jobs.

Not providing the correct secret key when starting the agent.

The agent will fail to authenticate and stay disconnected.

Use the exact secret key from Jenkins agent configuration when starting the agent.

Forgetting to disconnect an agent properly before maintenance.

Jenkins may still try to send jobs to the agent, causing failures.

Use the disconnect command or Jenkins UI to take the agent offline safely.

Summary

Start Jenkins agents with the correct JNLP URL and secret to bring them online.

Use disconnect commands or Jenkins UI to take agents offline safely for maintenance.

Check agent status regularly to avoid build failures caused by offline agents.