SSH, Inbound, WebSocket, Windows, and Ephemeral Agents: Connectivity, Remoting, and Agent Lifecycle: Concepts, Architecture, and Mental Model

1. The practical problem: “agent offline” is too vague

Chapter 17 modeled capacity: labels select eligible nodes, executors provide concurrency, and workspaces carry execution state. Chapter 18 asks a different question: how does the worker become a trusted, connected Jenkins agent in the first place, and what exactly breaks when it disconnects?

A node can be perfectly configured yet have no running agent process. An agent process can be running yet use the wrong Java. The network can be reachable yet the WebSocket upgrade can fail. SSH authentication can succeed to the wrong server if host identity is not verified. A Remoting channel can disconnect while the agent filesystem remains full of stale workspace files. Treating all of those as “agent down” leads to destructive or insecure fixes.

2. Mental model: configuration → identity → transport → Remoting → execution

The controller stores node configuration: name, labels, remote root, executor count and launcher. The launcher determines who initiates the connection and which bootstrap identity is used. The network transport then carries Jenkins Remoting. Remoting creates the controller↔agent communication channel. The agent JVM exposes executors and workspaces under an operating-system identity. Disconnecting or deleting the worker ends that execution context, but Jenkins build records and archived evidence are separate retained state.

flowchart TD
  A[Controller node configuration] --> B[Launcher and bootstrap identity]
  B --> C[SSH / inbound TCP / WebSocket transport]
  C --> D[Remoting channel]
  D --> E[Agent JVM and OS identity]
  E --> F[Executors and workspaces]
  F --> G[Build steps and evidence]
  G --> H[Disconnect / terminate / recreate]
  H --> I[Cleanup bootstrap material and workspace state]
  G --> J[Retained Jenkins build record / artifacts]

3. Five layers you should name explicitly

4. SSH and inbound launch reverse the connection direction

SSH Build Agents is controller-initiated. Jenkins reaches an SSH server on the worker, verifies the server identity, authenticates with a scoped credential and starts the agent. This is natural when the controller can reach stable Unix-like hosts.

Inbound agents are agent-initiated. The worker starts agent.jar and reaches Jenkins using a controller-generated agent secret. This is useful behind NAT/firewalls and common on Windows or ephemeral workers. The older term “JNLP agent” remains in some names, but Java Web Start is no longer the launch mechanism.

5. WebSocket: inbound connection over the web path

Without WebSocket, a normal inbound agent first reaches Jenkins over HTTP(S) to obtain connection data and then connects to the configured inbound-agent TCP port. With -webSocket, the agent uses a single HTTP(S)/WebSocket path. That can simplify firewall design, but the reverse proxy must support WebSocket upgrades and timeouts correctly.

# Shape only. Obtain agent.jar and the secret from YOUR disposable controller.
java -jar agent.jar \
  -url 'https://jenkins.example.invalid/' \
  -secret @/run/secrets/ch18-agent-secret \
  -name 'ch18-ws-a' \
  -webSocket \
  -workDir '/opt/jenkins-agent'

The @file form keeps the secret out of the literal command line. Protect the file with OS permissions and remove it when the disposable identity is retired.

6. Remoting is the channel, not the network itself

Jenkins Remoting is the communication layer used after the agent connects. It handles remote calls, data transfer and execution coordination between separate JVMs. For manually launched agents, download the matching agent.jar from the target controller at /jnlpJars/agent.jar instead of reusing an unknown local copy.

For the container lab, this chapter pins jenkins/inbound-agent:3391.va_37fa_a_305d6d-2-jdk21 as a reviewed 2026-09-17 image line. Record the image tag and digest for your architecture. A current image is not a reason to ignore the target controller’s compatibility or Java requirements.

7. Java belongs to the agent operating model

Jenkins 2.568.3 LTS is tested with Java 21 and 25, and Jenkins’ Java policy applies to system components including agents. A build may compile an application with a different toolchain later, but the agent JVM that runs Remoting must satisfy Jenkins’ runtime requirement.

java -version
java -jar agent.jar -help | head -n 20

Capture Java vendor/version/architecture and Remoting startup evidence before attributing disconnects to the network.

8. Windows: process identity matters more than the GUI

A Windows agent can run the same inbound agent.jar. For persistent operation, run it under a deliberate least-privilege service account or scheduled task with a fixed work directory and explicit restart policy. Jenkins documentation also describes Windows Scheduler as a fallback when service installation is unsuitable.

A Windows service normally does not interact with an interactive desktop. If a test truly requires an interactive user session, model that as a separate constrained pool; do not grant a service broad desktop or administrator privileges merely to make a GUI test work.

9. Ephemeral lifecycle: recreate execution state, retain build evidence

An ephemeral agent is expected to disappear after work. Therefore the workspace, local caches and process tree are not durable truth. Source revision, build number, logs, reports, archived artifacts and external target IDs must be retained independently.

Teardown should revoke or retire the worker’s bootstrap identity, remove temporary secret files and work roots, and confirm the old worker can no longer connect. If an inbound secret is compromised, Remoting guidance says not to reuse the affected agent name on that controller.

10. Read-only inspection before changing connectivity

pipeline {
  agent { label 'ch18-remote' }
  stages {
    stage('Agent evidence') {
      steps {
        sh '''
          set -eu
          printf 'node=%s\nlabels=%s\nworkspace=%s\n' \
            "$NODE_NAME" "$NODE_LABELS" "$WORKSPACE"
          id
          java -version 2>&1 | head -n 3
        '''
      }
    }
  }
}

On the node page, inspect launcher, online/offline state, connection log and remote root. On the agent, inspect Java, process identity, work directory and filesystem permissions. Record endpoint/proxy facts without printing the inbound secret or SSH private key.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog and Java support policy — lab baseline Jenkins 2.568.3 LTS; Jenkins system components, including agents, require Java 21 or 25 on this baseline.
• Using Jenkins agents and Managing Nodes — distributed execution, node configuration, Windows agent examples, and lifecycle concepts.
• Jenkins Remoting and Launching inbound agents — obtain agent.jar from the controller; inbound command, -webSocket, work directory, and direct TCP guidance.
• SSH Build Agents plugin — baseline 3.1097.v868116049892; SSH launch requires verified server identity and least-privilege agent credentials.
• Official Jenkins inbound-agent images — reviewed lab image line jenkins/inbound-agent:3391.va_37fa_a_305d6d-2-jdk21. Pin a reviewed tag/digest for repeatable labs rather than using latest.
• Controller Isolation — keep the built-in node at zero executors and do not use controller-local builds as a connectivity workaround.
• Installing Jenkins — standalone Jenkins uses the supported Jetty/Winstone stack; WebSocket-agent support depends on a compatible servlet/proxy path.